Integrating the Android SDK

Last Updated: Mar 13, 2015 05:31PM 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 2.2 (Froyo) and higher; please be sure you're using a compatible version of Android's framework for your application.
    • Starting August 1, 2014, Google is advising the use of the new Android Advertising ID for tracking and marketing purposes. While Apsalar's latest SDK may be compatible with Android versions lower than 2.2, it will not be able to utilize Android's new Advertising ID. 
    • Apsalar’s SDK will report using the new Android Advertising ID for devices using PlayStore v4. Older devices will continue to report using the ANDI.
    • Please note, use of the 6.X.X SDK has not been tested with Android versions lower than 2.2. Should you choose to use the 6.X.X SDK with an Android version lower than 2.2, 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. Set your Facebook App ID (Optional)

In order to track Facebook attributions for your application, you must set your Facebook App ID. Your Facebook App ID is s a 15 digit number unique to you as a developer on Facebook's platform. If you do not plan to track Facebook attributions, you may skip this step.

Please note, your Facebook App ID must be set in your application prior to initializing a session with Apsalar's SDK. To set your Facebook App ID, use the following call:

7. 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 onCreate() 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, "Your_Api_Key", "Your_Secret");​
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.

8. 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");

9. 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.

10. 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.

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