Support Center

Integrating the Android SDK

Last Updated: Oct 09, 2013 01:25PM PDT

1. Download the SDK 

Log in and download the sdk from the Get the SDK page under Developer Tools.

2. Install the SDK

  1. Unzip the file you downloaded and open your application project
  2. Add the .jar file to the lib directory
  3. If your application does not have a lib directory, place the .jar file in another directory and add the directory to your Java CLASSPATH variable

3. Integrate the SDK

Modify the AndroidManifest.xml file

  1. Add the necessary permissions to establish connection to Apsalar servers

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  2. Insert the following inside your main application tag:

    <activity android:name="com.apsalar.sdk.Activity"
  3. Add the following in the main application tag to enable attribution analytics

    <receiver android:exported="true" android:name="com.apsalar.sdk.ApsalarReceiver">
               <action android:name=""></action>
  4. Add the following in the main activity so your application can use ApEngage features

       <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/<package>" />

    where <package> is the package that you have defined for your app.

The following is an example of an AndroidManifest.xml file that will work with Apsalar:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android=""
   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   <application android:label="@string/app_name" android:icon="@drawable/icon">
      <activity android:name="ApTest"
            <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/<package>" />
      <activity android:name="com.apsalar.sdk.Activity"
      <receiver android:exported="true" android:name="com.apsalar.sdk.ApsalarReceiver">
                <action android:name=""></action>

Google Play Referral Tracking

The Android OS supports a referrer URL parameter in download links to Google Play. The source of the application install may be recorded and associated with subsequent events, which is useful for apps that contain a version of the Apsalar Android SDK version 4.0.0 or above. A typical URL might look like this, before encoding: referrer=a_getjar+ca_acquisitioncampaign+pl_300x50+i_taximagic+op_click

​As the URL indicates, parameters are carried forward in &referrer. Code contained in the AndroidManifest.xml can parse the referrer parameter and send those values to an end point. These parameters are passed to the Apsalar Referral API along with the additional relevant information to identify the user.

  • Device ID
  • Device Keyspace
  • Operating System

Additional details on Google Play Campaign Tracking can be found here.​​

Facebook Install Tracking

Starting with version 3.2.4, Apsalar's Android SDK supports Facebook Install Tracking. For Facebook Install Tracking to work, Apsalar requires the unique Facebook App ID, a 15-digit number that Facebook generates.

Add the following method call to activate Facebook Install Tracking (Please note, this method must be called before the Apsalar session is initiated):


​Start an Apsalar session

  1. Import Apsalar class libraries by adding the following to your main activity:

    		 import com.apsalar.sdk.Apsalar;
  2. Start a session by adding the following in the onCreate method of your application:

    		 Apsalar.startSession(Activity activity,String APIKey, String secret);

    using your assigned API Key and secret. These can be found under Developer Tools > Get the SDK.

    An example of this call is:


Start tracking events

  1. To track age and gender, use the following methods 
               Apsalar.setAge(int age);
    where age is an integer with values between 0 and 100

               Apsalar.setGender(String gender);
    where gender is a string with one of two values "f" or "m"
  2. Decide what events you want to track in your application. ApScience does not have any predefined event names, so you can create and use whatever name you like. You can also use the same event name in many places throughout your application, in the case where you actually track that event in more than one place. To help you with deciding which events and attributes to track, we have compiled a set of best practices
  3. Place calls to one the following three methods into your app for each place you want to track an event. This will register and record all event occurrences. Read about restrictions on event name and event attribute name and value.

    For an event without any arguments

    		Apsalar.event(String eventName);

    where eventName is the name you have chosen for this event

    An example of this call is:


    For an event with arguments

    		Apsalar.event(String eventName, Object... args);

    where args is 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, i.e. JSONObject, JSONArray, String, Boolean, Integer, Long, Double or NULL.

    An example of this call using primitive data types for the values is:

    		Apsalar.event("purchase", "quantity", 3, "product", "cotton shirt", "price", 42.34);

    For an event with arguments (JSONObject)

    		Apsalar.eventJSON(String name, JSONObject args);

    where args is 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.

    An example of these calls using a JSONObjects and JSONArrays to track shopping cart data could be:

    		import org.json.*;
    // create a JSON array for all of the items (content)
    // in the shopping cart and JSON objects for each
    // shopping cart item.  The total, member_id, and
    // currency type are added once for the entire shopping cart.
    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");
      // record the event with Apsalar
                    "contents", contents,
                    "total", 63.96,
                    "currency", "USD",
                    "member_id", "A556740089");
     // if and only if using Apsalar SDK 1.2.3 or higher,
     // you could also use the following method
     JSONObject args = new JSONObject();
     args.put("contents", contents);
     args.put("total", 63.96);
     args.put("currency", "USD");
     args.put("member_id", "A556740089");
     Apsalar.eventJSON("cart2", args);
    } catch(JSONException e) {
    android.util.Log.e("Now", "JSON Exception in cart");

4. 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.
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found