Tech docs
Integration Docs
Android Tracking SDK

Android Tracking SDK

The Parse.ly Android SDK is a Java library providing Parse.ly tracking functionality to native Android apps. Like any other framework you might include in your project, the Parse.ly SDK provides a programming interface usable from your application code.

The official repository is hosted on Github.

#Including the SDK in a project

If you want to track activity on your Android app, first download a release or clone the repository with:

git clone http://github.com/Parsely/parsely-android.git

The repository's primary purpose is to host the open source Parse.ly Android SDK, implemented as a Java module in /parsely. This module is symlinked in the /ParselyExample/app/src/main/java/com directory as an example of how to integrate the SDK in a typical Android Studio project. You can open ParselyExample as an Android Studio project and explore a typical SDK integration.

To integrate Parse.ly mobile tracking with your Android Studio app:

  1. Copy the parselyandroid directory to your project's top-level package directory (in a default Android Studio project, this is /app/src/main/java/com). The directory tree should look like /app/src/main/java/com/parsely/parselyandroid.
  2. In Build -> Edit Libraries and Dependencies under the Dependencies tab, use the green + to add two Library Dependencies: org.codehaus.jackson:jackson-core-lgpl:1.9.13 and org.codehaus.jackson:jackson-mapper-lgpl:1.9.13
  3. Add the following lines to your AndroidManifest.xml file:

    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  4. Add the following lines to app/build.gradle:

    packagingOptions {
        exclude 'META-INF/LGPL2.1'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/NOTICE'
    }

#Using the SDK

In any file that uses the Parsely SDK, be sure to add the line

import com.parsely.parselyandroid.*;

at the top of the file.

Before using the toolkit, you must initialize the Parsely object with your public siteId. This is usually best to do in the MainActivity's onCreate method.

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ParselyTracker.sharedInstance("example.com", this);
}

The Parsely toolkit maintains a queue of pageview events and periodically flushes it to Parse.ly servers. This helps extend the battery life of your users' Android devices. As a result of this design, there may be some pageview events remaining in the queue at the time the user exits your app. To make sure all of the queued events are flushed to the server at this time, make sure to include a call to flushEventQueue() in your main activity's onDestroy() method:

@Override
protected void onDestroy() {
    ParselyTracker.sharedInstance().flushEventQueue();
    super.onDestroy();
}

#API Documentation

#ParselyTracker.trackPageview

Register a pageview event using a URL and optional metadata.

ParameterTypeRequiredDescription
urlStringyesThe URL of the article being tracked (eg: "http://example.com/some-old/article.html")
urlMetadataMap<String, Object>noOptional metadata for the URL -- not used in most cases. Only needed when
extraDataMap<String, Object>noA Map of additional information to send with the event.

#ParselyTracker.startEngagement

Start engaged time tracking for the given URL.

This starts a timer which will send events to Parse.ly on a regular basis to capture engaged time for this URL. The value of url should be a URL for which trackPageview has been called.

ParameterTypeRequiredDescription
urlStringyesThe URL of the article being tracked (eg: "http://example.com/some-old/article.html")
urlRefStringnoReferrer URL associated with this video view.

#ParselyTracker.stopEngagement

Stops the engaged time tracker, sending any accumulated engaged time to Parse.ly.

NOTE: This must be called in your MainActivity during various Android lifecycle events like onPause or onStop. Otherwise, engaged time tracking may keep running in the background and Parse.ly values may be inaccurate.

#ParselyTracker.trackPlay

Starts tracking view time for a video being viewed at a given url. Will send a videostart event unless the same url/videoId had previously been paused. Video metadata must be provided, specifically the video ID and video duration.

The url value is not the URL of a video, but the post which contains the video. If the video is not embedded in a post, then this should contain a well-formatted URL on the customer's domain (e.g. http://<CUSTOMERDOMAIN>/app-videos). This URL doesn't need to return a 200 status when crawled, but must but well-formatted so Parse.ly systems recognize it as belonging to the customer.

ParameterTypeRequiredDescription
urlStringyesURL of post the video is embedded in. If videos is not embedded, a valid URL for the customer should still be provided. (e.g. http://<CUSTOMERDOMAIN>/app-videos)
urlRefStringnoReferrer URL associated with this video view.
videoMetadataMap<String, Object>yesMetadata about the video being tracked.
extraDataMap<String, Object>noA Map of additional information to send with the event.

#ParselyTracker.trackPause

Pause video tracking for an ongoing video. If trackPlay is immediately called again for the same video, a new videostart event will not be sent. This models a user pausing a playing video.

NOTE: This or resetVideo must be called in your MainActivity during various Android lifecycle events like onPause or onStop. Otherwise, engaged time tracking may keep running in the background and Parse.ly values may be inaccurate.

#ParselyTracker.resetVideo

Stops video tracking and resets internal state for the video. If trackPlay is immediately called for the same video, a new videostart event is set. This models a user stopping a video and (on trackPlay being called again) starting it over.

NOTE: This or trackPause must be called in your MainActivity during various Android lifecycle events like onPause or onStop. Otherwise, engaged time tracking may keep running in the background and Parse.ly values may be inaccurate.

#ParselyTracker.flushEventQueue

Empties the event queue and sends the appropriate requests to Parsely. Called automatically after a number of seconds determined by flushInterval.

To make sure all of the queued events are flushed to Parse.ly's servers, include a call to flushEventQueue() in your main activity's onDestroy() method.

#ParselyMetadata

This class is used to attach a metadata block to a Parse.ly pageview request. Pageview metadata is only required for URLs not accessible over the internet (i.e. app-only content) or if you are using an "in-pixel" integration. Otherwise, metadata will be gathered by Parse.ly's crawling infrastructure.

ParameterTypeRequiredDescription
authorsArrayList<String>noThe names of the authors of the content. Up to 10 authors are accepted.
linkStringnoA post's Parse.ly canonical URL.
sectionStringnoThe category or vertical to which this content belongs.
tagsArrayList<String>noUser-defined tags for the content. Up to 20 are allowed.
thumbUrlStringnoURL at which the main image for this content is located.
titleStringnoThe title of the content.
pubDateCalendarnoThe date this piece of content was published.

#ParselyVideoMetadata

This class is an implementation of ParselyMetadata for videos.

ParameterTypeRequiredDescription
authorsArrayList<String>noThe names of the authors of the video. Up to 10 authors are accepted.
videoIdStringyesUnique identifier for the video.
sectionStringnoThe category or vertical to which this video belongs.
tagsArrayList<String>noUser-defined tags for the video. Up to 20 are allowed.
thumbUrlStringnoURL at which the main image for this video is located.
titleStringnoThe title of the video.
pubDateCalendarnoThe date this video was published.
durationSecondsintyesDuration of the video in seconds.
rocket emoji