Mobile SDK: Android tracking overview and configuration
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:
- 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
. - In
Build -> Edit Libraries and Dependencies
under theDependencies
tab, use the green+
to add two Library Dependencies:org.codehaus.jackson:jackson-core-lgpl:1.9.13
andorg.codehaus.jackson:jackson-mapper-lgpl:1.9.13
- 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">
- 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 this line at the top of the file:
import com.parsely.parselyandroid.*;
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();
}
Providing metadata
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.
NOTE for the metadata integration types below, it is possible to send a canonical URL that does not need to resolve to an extant page when navigated to in a browser. If you do this, it is important that the canonical URL provided for the mobile post should still be a URL with the domain matching a domain from which other traffic is sent for the Site ID. The URL should also be unique to the post among all posts for the Site ID.
There are two methods for providing Parse.ly with metadata for content that’s only accessible via the Mobile SDK:
- Primary recommendation: updating metadata using the metadata API endpoint.
- Back-up option: Sending metadata “in-pixel” with every event sent with the Mobile SDK. This should be used only in special cases. For example, this is an appropriate method for a mobile-app only company.
API Documentation
ParselyTracker.trackPageview
Register a pageview event using a URL and optional metadata. Should only be called once per page view.
Parameter | Type | Required | Description |
---|---|---|---|
url | String | yes | The URL of the article being tracked (eg: “http://example.com/some-old/article.html“) |
urlMetadata | Map<String, Object> | no | Optional metadata for the URL — not used in most cases. Only needed when url isn’t accessible over the Internet (i.e. app-only content). Do not use this for content also hosted on URLs Parse.ly would normally crawl. |
extraData | Map<String, Object> | no | A Map of additional information to send with the event. |
ParselyTracker.startEngagement (heartbeat tracking)
Recommended implementation: Call startEngagement
when a post is navigated to, and to call stopEngagement
when it’s navigated away from.
Start engaged time tracking for the given URL. Once called, heartbeat events will automatically be sent periodically to capture engaged time for this url until engaged time tracking is stopped.
This call also automatically stops tracking engaged time for any urls that are not the current url.
The value of url
should be a URL for which trackPageview
has been called.
Parameter | Type | Required | Description |
---|---|---|---|
url | String | yes | The URL of the article being tracked (eg: “http://example.com/some-old/article.html“) |
urlRef | String | no | Referrer URL associated with this video view. |
extraData | Dictionary<String, Any>? | no | A dictionary of additional information to send with the generated heartbeat events |
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:///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.
Parameter | Type | Required | Description |
---|---|---|---|
url | String | yes | URL 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:///app-videos) |
urlRef | String | no | Referrer URL associated with this video view. |
videoMetadata | Map<String, Object> | yes | Metadata about the video being tracked. |
extraData | Map<String, Object> | no | A 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
NOTE: This metadata class is functionally limited. It does not contain all metadata values. Only use this class to provide metadata if you are choosing to not use the recommended method above.
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.
Parameter | Type | Required | Description |
---|---|---|---|
authors | ArrayList | no | The names of the authors of the content. Up to 10 authors are accepted. |
link | String | no | A post’s Parse.ly canonical URL. |
section | String | no | The category or vertical to which this content belongs. |
tags | ArrayList | no | User-defined tags for the content. Up to 20 are allowed. |
thumbUrl | String | no | URL at which the main image for this content is located. |
title | String | no | The title of the content. |
pubDate | Calendar | no | The date this piece of content was published. |
ParselyVideoMetadata
This class is an implementation of ParselyMetadata
for videos.
Parameter | Type | Required | Description |
---|---|---|---|
authors | ArrayList | no | The names of the authors of the video. Up to 10 authors are accepted. |
videoId | String | yes | Unique identifier for the video. |
section | String | no | The category or vertical to which this video belongs. |
tags | ArrayList | no | User-defined tags for the video. Up to 20 are allowed. |
thumbUrl | String | no | URL at which the main image for this video is located. |
title | String | no | The title of the video. |
pubDate | Calendar | no | The date this video was published. |
durationSeconds | int | yes | Duration of the video in seconds. |
Last updated: January 06, 2023