Android Analytics SDK
Overview
The Liftoff SDK is a thin and light attribution SDK which will take about 15 minutes to integrate.
- Add the Liftoff SDK to your Android project.
- Record installs.
- Record other in-app engagement events.
- 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
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.
- You can optionally also download the SDK source code if you would like
to review it, but to avoid compatibility issues please use the
Add the SDK to your app.
- Put the SDK .jar in the
libs/
directory of your Android project. - In your project's
AndroidManifest.xml
, make sure that yourminSdkVersion
is at least 7. - Also in the project manifest, ensure that your app has the
INTERNET
permission.
- Put the SDK .jar in the
Add the Google Play Services SDK to your app by following the instructions from the Android developer website.
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:
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:
<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!