Integrating the Android SDK (Pre-7.0.0)

Last Updated: Jun 29, 2017 01:08PM PDT

1. Initial Requirements and Information

Before installing the SDK into your application, please review the following items to ensure integrating the SDK into your application is a smooth and easy process:
  • If you are upgrading from a previous version of the Android 4.X.X SDK, please use this upgrade guide.
  • Apsalar's latest Android SDKs, 6.X.X, supports Android 4.0.1 (Ice Cream Sandwich) and higher; please be sure you're using a compatible version of Android's framework for your application.
    • Apsalar’s SDK reports using the Android Advertising ID for devices using PlayStore v4. Older devices will continue to report using the ANDI.
    • Please note, use of the latest 6.X.X SDK has not been tested with Android versions lower than 4.0.1. Should you choose to use the latest 6.X.X SDK with an Android version lower than 4.0.1, Apsalar's Product Support Team may not be able to assist with any issues that arise.

2. Download the SDK

Log in and download the SDK by selecting Get the SDK under Developer Tools.

3. Import Apsalar and other necessary libraries into your application

To use Proguard with your app

  • Add the following lines of code to your proguard.config file:
-keep class
-keep class com.apsalar.sdk.** { *; }


4. Add Necessary Permissions to your Applications Manifest File

The following list of permissions are those which Apsalar's SDK can utilize; each desired permission should be added in the <manifest> tag in your AndroidManifest.xml file. Please refer to the list below to understand which permissions are required and which are optional: 
  • INTERNET - Required
    • Add the following to your manifest tag:
      <uses-permission android:name="android.permission.INTERNET" />
    • Add the following to your manifest tag:
      <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
​​Please note, Android SDKs 4.X.X and 6.0.X required the WRITE_EXTERNAL_STORAGE permission, which is no longer required for SDKs 6.1.X+. 

5. Add the Apsalar Receiver

The Apsalar Receiver is designed to forward INSTALL_REFERRER data to any additional receivers listening for the INSTALL_REFERRER intent. The Apsalar Receiver MUST be the first receiver in your manifest file in order to properly forward data to additional receivers. Instructions for testing the implementation of the Apsalar Receiver can be found in our Event Tracking Console Guide.

To implement the receiver:

  • Add the following to your <application> tag in your manifest file:
    <receiver android:exported="true" android:name="com.apsalar.sdk.ApsalarReceiver">
               <action android:name=""></action>
  • Unregister the receiver when your app exits, by updating your Activity's onPause() method: 
    protected void onPause() {
  • Here is sample AndroidManifest.xml file configured with the receiver:
    <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android=""
      <uses-sdk android:minSdkVersion="9" android:targetSdkVersion="19" />
      <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
      <uses-permission android:name="android.permission.INTERNET" />
      <application android:label="@string/app_name" android:icon="@drawable/icon" android:allowBackup="true">
        <activity android:name="SampleActivity"
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <category android:name="android.intent.category.DEFAULT" />
            <data android:scheme="http"
                  android:pathPrefix="/api/v1/appstore/" />
        <meta-data android:name=""
        <receiver android:exported="true" android:name="com.apsalar.sdk.ApsalarReceiver">
               <action android:name=""></action>

6. Start an Apsalar session

To properly track events for your application and accurately monitor session lengths, an Apsalar session must be initiated when the user launches the application. Use the following steps to initialize an Apsalar session:
  • Import the Apsalar class libraries to your main activity with the following:
    import com.apsalar.sdk.Apsalar;
  • Add the startSession call to the onResume() method of your main activity using your Apsalar API key and secret. Your API Key and secret can be obtained from the Get the SDK page on your account:
    Apsalar.startSession(currentActivity.getApplicationContext(), "Your_Api_Key", "Your_Secret");​
  • If your app is using Apsalar Android SDK 6.4.0+ or above, and is utilizing deeplinks, pass the intent data to the Apsalar startSession. Note: this is required if you would like to run Google app engagement campaigns which require deeplinking technology.  Please ensure the Apsalar StartSession for these scenarios trigger whenever the application is opened either from an install or from a deeplink open.
    Intent intent = getIntent();
      Uri data = intent.getData();
      ​Apsalar.startSession(currentActivity.getApplicationContext(), "Your_Api_Key", "Your_Secret", data);​
Note: The instructions above apply if you want to count a session as the time from the start of the main activity until the time that the activity is shut down or the process is killed. If you only want to record the time that the activity is running in the foreground, or would like to have more control over the recording of session counts and length, please review our documentation about Managing Session Lengths and Counts with the Android SDK.

7. Start Tracking Events

The first step is to decide which events you would like to track in your application. While there are a few restrictions on event and attribute names, you can generally use whichever names you prefer. To help you decide which events and attributes to track, we have compiled a set of best practices.

Once you've decided which events to track, you can begin implementing each event with the appropriate method from below:

For Revenue Events

We offer different solutions based on how much detail you'd like to track for your Revenue events. Please see our guide for configuring revenue events for more specific information.

Events Without Arguments

Apsalar.event(String eventName);
//Example call

Events With Arguments

Apsalar.event(String eventName, Object... args);
//Example call
Apsalar.event("Purchase_Complete", "quantity", 3, "product", "cotton shirt", "price", 42.34);
'args' must be one or more attribute/value pairs where the attribute is a string of the attribute's name and the value is any of the allowable types( JSONObject value, i.e. JSONObject, JSONArray, String, Boolean, Integer, Long, Double or NULL). Please note, event arguments must exist as name-value pairs. If the args list contains an odd number of elements, then the name-value mapping is unbalanced and the event will be rejected by Apsalar's servers.

Events With JSONObject Arguments

Apsalar.eventJSON(String name, JSONObject args);

'args' must be a JSONObject containing one or more attribute/value pairs where the attribute is a String that you have chosen as the attribute name and the value is any type allowable as a JSONObject value. Here is an example of these calls using a JSONObjects and JSONArrays to track shopping cart data:
import org.json.*

try {
  JSONArray contents = new JSONArray();
  JSONObject item1 = new JSONObject();

  item1.put("sku", "UPC-018627610014");
  item1.put("qty", 2);
  item1.put("unit_price", 8.99);
  item1.put("currency", "USD");

  JSONObject item2 = new JSONObject();
  item2.put("sku", "UPC-070271003758");
  item2.put("qty", 1);
  item2.put("unit_price", 15.99);
  item2.put("currency", "USD");

  JSONObject item3 = new JSONObject();
  item3.put("sku", "UPC-070271003758");
  item3.put("qty", 1);
  item3.put("unit_price", 15.99);
  item3.put("currency", "USD");

  JSONObject args = new JSONObject();
  args.put("contents", contents);
  args.put("total", 63.96);
  args.put("currency", "USD");
  args.put("member_id", "A556740089");

  // Record the event with Apsalar
  Apsalar.eventJSON("Purchase_Complete", args);
catch(JSONException e) {
  android.util.Log.e("Now", "JSON Exception in cart");

8. End an Apsalar Session

Apsalar counts the end of a session as the timestamp of the last event that occurred before a new session is started. If you want to count a session as the time from the start of the main activity until the time that the activity is shut down or the process is killed, there is no need to explicitly end the session. However, if you would like more control over when a session ends, you can use the Apsalar.endSession() method in conjunction with disabling the heartbeat (described in the Optional Android 6.X.X Features section below), as explained in our documentation about Managing Session Lengths and Counts with the Android SDK.

9. Compile and Run

Compile and run your application to automatically register your application and events. User data should start populating on your dashboard within a few hours.

Note: Event attributes will populate with some delay, after Apsalar batch reports are run.

Optional Android 6.X.X Features

The following items are additional features and options available in Apsalar's 6.X.X Android SDK.

Uninstall Tracking

Note: For all the steps to enable uninstall tracking, please see this guide here.  This section only details the updates required for your app, to allow Apsalar to track your Android app's uninstalls.

With Apsalar's Android SDK version 6.2.0 and on, you can track your app's uninstalls with Apsalar.  To enable your Android app to support Apsalar uninstall tracking, follow the simple steps below.  

1. Update the Apsalar Android SDK
To update your Android app to support Apsalar uninstall tracking, download the latest Apsalar Android SDK here and update your build.   

2. Incorporate Google Play Services

Uninstall tracking uses the services provided by the Google Cloud Messaging (GCM) platform.  In order to integrate this service, ensure Google Play Services is included in your build.  Follow Google's instructions to include Google Play Services here:​

Please be aware of GCM requirements on supported Android versions:


Here are the requirements for running a GCM Android client:
  • GCM requires devices running Android 2.2 or higher that also have the Google Play Store application installed, or an emulator running Android 2.2 with Google APIs. Note that you are not limited to deploying your Android applications through Google Play Store.
  • However, if you want to continue to use new GCM features that are distributed through Google Play Services, the device must be running Android 2.3 or higher, or you can use an emulator running Android 2.3 with Google APIs.
  • On Android devices, GCM uses an existing connection for Google services. For pre-3.0 devices, this requires users to set up their Google accounts on their mobile devices. A Google account is not a requirement on devices running Android 4.0.4 or higher.

Users/devices who are not running on supported versions of Android will not be available for Apsalar uninstall tracking.

Note: If you are already using GCM services in your application, please advise with Apsalar support team on our best practice implementation. 

3. Update the AndroidManifest File
Lastly, update your AndroidManifest.xml file to add the necessary permissions for your app.  The permissions required are the following (replace <your-package-name> with the your app's package name.  e.g. com.example.apsalar):
<uses-permission android:name="android.permission.WAKE_LOCK" />
<permission android:name="<your-package-name>.permission.C2D_MESSAGE" android:protectionLevel="signature" />
<uses-permission android:name="<your-package-name>.permission.C2D_MESSAGE" />
<uses-permission android:name="" />


Control Heartbeat

Apsalar’s Android SDK sends a heartbeat to Apsalar servers at a responsible rate to properly track session lengths and dequeue events that are collected during offline operation.. The heartbeat starts after 5 minutes and remains active until session end. The time between subsequent heartbeats is doubled after each heartbeat until it reaches at a maximum of 6 hours, ensuring minimal network usage.

However, some app developers need fine control over a device’s network connections and to meet this need, our Android API provides two methods to control heartbeat:
boolean Apsalar.isHeartbeatEnabled() // Returns true if enabled, false if disabled
boolean Apsalar.enableHeartbeat(boolean) // Use true to enable, false to disable

Age and Gender

In Apsalar's continued effort to provide with thorough insight into how your application's are being utilized, we've provided two methods to set the age and gender for users. Currently, we do not report this data in our UI, but we hope to develop this feature in the future. You can begin passing this information and the historical data will be available to you when these dimensions are added to Apsalar's reporting. To set age and gender, please use the following methods:
Apsalar.setAge(int age); // Where age is integer between 0 and 100
Apsalar.setGender(String gender); // Where gender is either 'f' or 'm'
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found