Skip to main content

Android Analytics SDK

Overview​

The Liftoff SDK is a thin and light attribution SDK which will take about 15 minutes to integrate.

  1. Add the Liftoff SDK to your Android project.
  2. Record installs.
  3. Record other in-app engagement events.
  4. Verify that it's working by visiting our testing harness dashboard (link available in the developer page within the customer dashboard).

A few notes about the Analytics SDK:

  • It works with Android 2.1 (API level 7) and higher.
  • It requires Android's INTERNET permission in order to communicate with Liftoff's servers (your app almost certainly already has this permission turned on).
  • It collects the Android Advertising ID and the "Limit Ad Tracking" setting, if available on the device. In order to ensure we can make use of this information, you'll need to also incorporate the Google Play Services into your app.

Add the Liftoff SDK to your Android project​

  1. Download the latest version of the Liftoff SDK JAR (2.1.0).

    • You can optionally also download the SDK source code if you would like to review it, but to avoid compatibility issues please use the .jar file for your actual integration, not the source code.

  2. Add the SDK to your app.

    1. Put the SDK .jar in the libs/ directory of your Android project.
    2. In your project's AndroidManifest.xml, make sure that your minSdkVersion is at least 7.
    3. Also in the project manifest, ensure that your app has the INTERNET permission.

  3. Add the Google Play Services SDK to your app by following the instructions from the Android developer website.

  4. Add the import line to the Java source file of your main activity, and to any other locations in your project where you intend to call Liftoff API methods:

import io.liftoff.sdk.Liftoff;

Record installs and sessions​

SDK Initialization​

When your application starts, use the getInstance method to get the Liftoff singleton object you will use for reporting. You will need to provide your app's application context, your API key, and your Liftoff App ID. This should be done in your main Application class:

MainApplication.java
import io.liftoff.sdk.Liftoff;

public class MainApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    Liftoff.getInstance(this, API_KEY, APP_ID);
  }
}

Your API Key and App ID can be found in the developer page within the customer dashboard.

Collect the Google Play referrer and register an install​

Whenever your app is installed on a device, Android broadcasts an Intent containing the Google Play Install referrer. This is an important attribution value which must be passed into Liftoff's SDK.

You'll need to configure a BroadcastReceiver which listens for this Intent. This can be done by adding this XML fragment to your AndroidManifest.xml inside the <application> element:

AndroidManifest.xml
<receiver android:name="io.liftoff.sdk.ReferrerReceiver" android:exported="true">
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

However, if your app contains multiple SDKs which all need to know about the Google Play Referrer, you should implement your own BroadcastReceiver instead of using Liftoff's. This custom BroadcastReceiver should extract the referrer from the Intent and pass it into each SDK:

public class ReferrerReceiver extends BroadcastReceiver {
  @Override
  public void onReceive(Context context, Intent intent) {
    // Pass the referrer to Liftoff, which will register the install
    new io.liftoff.sdk.ReferrerReceiver().onReceive(context, intent);

    // Pass the referrer to additional SDKs here.
    // ...
  }
}

Register user sessions​

Once this is done, you should call startSession on the Liftoff singleton object. This records a new_session event. We recommend putting this code in the onCreate handler of your application's main Activity.

Here is a sample code snippet:

import io.liftoff.sdk.Liftoff;

public class MainActivity extends Activity {
  Liftoff liftoff;
  public void onCreate(Bundle savedInstanceState) {
    liftoff = Liftoff.getInstance();
    liftoff.startSession();
  }
}

A note about sessions​

The Android platform does not provide a method for our library to detect when users switch away from your application and back to it again (that is, to determine precisely when a user session starts and ends). If you would like Liftoff to accurately record user sessions, you should consider implementing session tracking for your app yourself and call startSession each time a user session starts. See these two links for more information.

Record other engagement/activation events​

Recording engagement events like "signup", "purchase" or "tutorial_complete" is important because we can then buy ads which optimize for post-install behavior like purchasing rather than just installs.

Use this code snippet to record events:

Liftoff.getInstance().recordEvent("signup");

You can track up to 100 different events. They will show up in the Liftoff analytics dashboard and can also be used to optimize Liftoff's ad buying. We recommend lowercase event names with underscores instead of spaces.

You should not use programmatically generated strings (i.e. that are user-specific) as event names; instead use hard-coded strings such as signup that describe a general point in your application's user flow.

Note that our analytics system also takes care of counting the number of users for whom a given event has occurred. So if you already have a purchase event, for example, you do not need to also log a first_purchase event.

Tracking revenue (transaction amounts) on your events​

If your app has purchase events, you can optionally record a revenue amount for those events. This makes it easier to see how much revenue is resulting from your marketing spend in the Liftoff UI.

Liftoff.getInstance().recordEvent("purchase", 12.50, "USD");

The third parameter is a currency code, which is a 3-letter ISO 4217 code. Common ones are: USD, GBR, EUR, AUD, CAD, JPY, CNX, MXN. A full list can be found here.

Verify that it's working​

Once you've integrated the SDK, launch your app on a phone. You should see the last few events that we've seen from your app in the testing dashboard (link is displayed in the developer page within the customer dashboard), grouped by app version.

If you don't see your events, contact your CSM to troubleshoot.

That's it!