Android SDK — Getting Started

You can get started with using Taplytics on your Android phones and Android TV / Fire TV devices in minutes. Just follow the steps below:

# Step
1 Android Studio Installation
2 Initialize SDK
3 Setting User Attributes (optional)
4 Tracking Events (optional)

You can use Taplytics to create Experiments as well as send Push Notifications to your app.

1. Installation

Android Studio

  1. In your module’s build.gradle, add the url to the sdk.

     repositories {                                                                                              
         maven { url "" }
  2. In your module’s build.gradle dependencies (not your project's build.gradle), compile Taplytics and its dependencies.
    NOTE: You can use EITHER Retrofit2 or Volley.

     dependencies {                                                                  
         //Dependencies for Taplytics
         compile 'com.taplytics.sdk:taplytics:+@aar'  
         // connections only made on debug devices.
         //To make live changes on a release build, remove the `debugcompile` flag
         debugCompile ('') {
              exclude group: 'org.json', module: 'json'
         //NOTE: You can use either Volley or Retrofit2. Do not use both if you do not have to.
         compile ''
         compile 'com.squareup.retrofit2:retrofit:+'
         //Only include this if you wish to enable push notifications:

    Click here to read more about the recent socket dependency changes.

  3. Override your Application’s onCreate() method (not your main activity) and call Taplytics.startTaplytics(). If you don't have an Application class, create one. It should look like this:

     public class ExampleApplication extends Application {
         public void onCreate() {
             Taplytics.startTaplytics(this, "YOUR TAPLYTICS API KEY");
  4. Now, add the proper permissions, and the Application class to your app’s AndroidManifest.xml in the Application tag.

     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  5. To be able to connect to Taplytics on a release build, add the following intent-filter tag to the end of your MAIN activity:

    First, get your Taplytics URL Scheme from your Project's Settings:


    Then, add it to your manifest in its own intent filter (do not merge with another intent filter).

                     <action android:name="android.intent.action.VIEW"/>
                     <category android:name="android.intent.category.DEFAULT"/>
                     <category android:name="android.intent.category.BROWSABLE"/>
                     <data android:scheme="YOUR URL SCHEME"/>
  6. That's it! Now build and run your app, you can start creating experiments with Taplytics!


The Taplytics SDK can also be installed via Segment. You can find install instructions here


2. Initialization

Taplytics can be started with a few options to help you use it during development.

First, the base method:

Taplytics.startTaplytics(this, "Your Api Key");

Or, add a map of options.

HashMap<String, Object> options = new HashMap<>();
options.put("optionName", optionValue);
Taplytics.startTaplytics(this, "Your Api Key", options);

Start Options

Option Name Values Default Explanation
liveUpdate boolean: true/false set by build (enabled in debug) Disable live update to remove the border, and activity refreshing in your debug builds to test the functionality of your applications as if they were in release mode. Note that this functionality is always disabled by default in release builds. Setting liveUpdate to true on a release build will override this and force the application into debug mode.
shakeMenu boolean: true/false set by build (enabled in debug) In your debug builds, disable the quick menu that appears when you shake your device. This menu is never present in release builds.
aggressive boolean false Taplytics has the option to allow for aggressive visual changes. This means that if text or visibility is changed within your app by code outside of Taplytics, Taplytics will force the values to remain what has been set on the dashboard.
sessionMinutes int > 0 10 If you do your own analytics alongside Taplytics, it helps to define your sessions to be the same length to reconcile your data. Set this to be the same timing interval that your app counts sessions.
turnMenu boolean: true/false false If you are doing visual testing on an emulator, or UI automation, many emulators do not have the ability to shake the device. So, to pop up the Taplytics menu on such devices, set turnMenu to true, and simply rotate the device from portrait/landscape twice in a row within 30 seconds and this menu will show.
disableBorders boolean: true/false set by build (enabled in debug) This will entirely disable the informational borders Taplytics applies during debug mode testing. Useful to disable for UI testing. Note that this border will NOT show in release mode regardless of setting (except for on previously paired phones).
testExperiments HashMap null See: Testing Specific Experiments.
retrofit boolean: true/false set by build (true if only retrofit present) Taplytics will default to using Volley if it is present. In the event that you have both enabled, you can use this flag to force the library to use retrofit instead.


Timeouts have since been removed from individual callbacks and have been added as a starting parameter.

By default the timeout is 4000ms. After this timeout has been reached, Taplytics will use only whatever values were loaded from disk for the remainder of the session. All variableUpdated callbacks will trigger, all getRunningExperimentsAndVariations will return with disk values, and the TaplyticsExperimentLoadedListener will trigger. The new values will still attempt to download and they will be cached and ready to be used for the next session.


Taplytics.startTaplytics(Context, ApiKey, Options, TimeoutInMillis)


Taplytics.startTaplytics(Context, ApiKey, TimeoutInMillis)


The Border / Shake menu.

When connected to an experiment on a debug build, a border will show around your app window. This shows which experiment and variation you are currently viewing.

You can long-press on the top of the border to switch experiments, or shake your device and pick from the menu, or select an experiment from the Taplytics website.

The border and shake menu will NOT appear on release builds.

Showing the menu without shaking or turning.

Taplytics offers a Taplytics.showMenu() function that can be used to call up the experiment menu. This is useful for testing environments that cannot shake or turn the device.

User Opt-In / Opt-Out

Using the User Opt-In / Opt-Out APIs allows you to simplify the process to get user consent for analytics tracking and experimentation. Calling optOutTracking will disable all Taplytics analytics tracking and experiments, and calling optInTracking will re-enable all Taplytics analytics tracking and experiments. You can retrieve the current status using: hasUserOptedOutTracking.

// Opt In

// Opt Out

// Check if user has opted out
Taplytics.hasUserOptedOutTracking(this, new TaplyticsHasUserOptedOutListener() {
    public void hasUserOptedOutTracking(boolean hasOptedOut) {
        // use hasOptedOut:
        // true: user has opted out
        // false: user has opted in

3. Setting User Attributes

It's possible to send custom user attributes to Taplytics using a JSONObject of user info.

The possible fields are:

Parameter Type
email String
user_id String
firstname String
lastname String
name String
age Number
gender String

You can also add anything else you would like to this JSONObject and it will also be passed to Taplytics.

An example with custom data:

JSONObject attributes = new JSONObject();
attributes.put("email", "");
attributes.put("name", "John Doe");
attributes.put("age", 25);
attributes.put("gender", "male");
attributes.put("avatarUrl", "");

attributes.put("someCustomAttribute", 50);
attributes.put("paidSubscriber", true);
attributes.put("subscriptionPlan", "yearly");


You can also attach a callback to notify you when user attributes has finished calling:

Taplytics.setUserAttributes(attributes, new TaplyticsSetUserAttributesListener() {
    public void finishedSettingUserAttributes() {
        // Finished setting user attributes

User Attributes on First Launch

User Attributes set before startTaplytics is called will be used for experiment segmentation on the first session of your app. Any attributes that are set after startTaplytics is called will not be used for experiment segmentation until the next session of your app.

// These custom data values will be used for segmentation on the first session of the app.

JSONObject attributes = new JSONObject();
attributes.put("example", 1);

Taplytics.startTaplytics(this, APIKEY)

// These custom data values will only take effect on the second session of the app.

JSONObject attributes = new JSONObject();
attributes.put("example", 0);

Retrieving Session Info

Taplytics also offers a method to retrieve select information of what you know about a session at a given time. This method returns the user's Taplytics identifier (appUser_id) and current session id (session_id)

Taplytics.getSessionInfo(new SessionInfoRetrievedListener() {
    public void sessionInfoRetrieved(HashMap sessionInfo) {
        //Use your Hashmap of Session Info

Resetting user attributes or Logging out a user

Once a user logs out of your app, their User Attributes are no longer valid. You can reset their data by calling resetAppUser, make sure you do not set any new user attributes until you receive the callback.

Taplytics.resetAppUser(new TaplyticsResetUserListener() {
    public void finishedResettingUser() {
        //Finished User Reset

4. Track Events

Automatic Events

Some events are automatically tracked by Taplytics and will appear on your dashboard. These events are:

  • App Start
  • Activity and/or Fragment load
  • Activity and/or Fragment destroy
  • Activity pause
  • App background
  • Viewpager changes

App terminate is also tracked, but this is only true when your MAIN activity is at the bottom of your activity stack, and the user exits the app from that activity.

No changes are needed in your code for this event tracking to occur.

Custom Events

To log your own events, simply call:

Taplytics.logEvent("Your Event Name");

You can also log events with numerical values:

Number num = 0;
Taplytics.logEvent("Your Event Name", num);

And with custom object data:

Number num = 0;
JSONObject customInfo = new JSONObject();
customInfo.put("some title", someValue)
Taplytics.logEvent("Your Event Name", num, customInfo);

Revenue Logging

It's also possible to log revenue.

Revenue logging is the same as event logging, only call logRevenue:

Number someRevenue = 10000000;  
Taplytics.logRevenue("Revenue Name", someRevenue);

And similarly, with custom object data:

Number someRevenue = 10000000;
JSONObject customInfo = new JSONObject();
customInfo.put("some rag", someValue)

Taplytics.logRevenue("Revenue Name", someRevenue, customInfo);

5. Receiving External Analytics

At the moment, Taplytics supports Mixpanel, Google Analytics, Adobe Analytics, Flurry, Localytics and Amplitude as a source of external analytics.

Mixpanel, Adobe, Localytics and Amplitude

When the Taplytics SDK is installed alongside any of these sources, all of your existing and future analytics events will be sent to both the source and Taplytics.


To properly support sending Flurry data, you simply need to tell Taplytics whenever a new Flurry session begins. This can be done directly after Flurry initialization.

FlurryAgent.init(this, "your flurry API key");

FlurryAgent.setFlurryAgentListener(new FlurryAgentListener() {
    public void onSessionStarted() {
Google Analytics 7.0.0-

If you are using Google Analytics 7.0.0 and below, all Google Analytics will automatically be sent to both Google Analytics and Taplytics.

Google Analytics 7.3.0+

If you are using Google Analytics 7.3.0 or above, you have the option of changing things to send your Google Analytics to both Google and Taplytics.

Simply find all instances of tracker.send(new Hitbuilder...) and replace them with Taplytics.logGAEvent(tracker, new Hitbuilder...)

You can do this with a simple find/replace in your application.

An example:

Tracker t = TrackerManager.getInstance()
                          .getGoogleAnalyticsTracker(TrackerManager.TrackerName.APP_TRACKER, getApplication());
t.send(new HitBuilders.EventBuilder()

Would be changed to:

Tracker t = TrackerManager.getInstance()
                          .getGoogleAnalyticsTracker(TrackerManager.TrackerName.APP_TRACKER, getApplication());
Taplytics.logGAEvent(t, new HitBuilders.EventBuilder()

6. Sending to External Analytics

Taplytics can send experiment data to external analytics sources on startup. This integration is automatic with the exception of Google Analytics where the tracker instance must be passed as a startup option to Taplytics.

HashMap<String, Object> options = new HashMap<>();
options.put("gaTracker", tracker);
Taplytics.startTaplytics(this, "YOUR API KEY", options);

The experiment data will be sent as a single event to Adobe, Amplitude, Flurry, and Localytics. The event will be named TL_experiments and have the experiment data as properties.

For both Google Analytics and Mixpanel, the experiment data will be set as properties on all the events (known as super properties in Mixpanel).

The properties for all sources are in the following format:

"Experiment One":"Variation One",
"Experiment Two":"baseline"


Device Pairing

Link a device (even in release mode) to Taplytics.

NOTE: This is used only for deeplink pairing.

Retrieve deeplink through Taplytics deeplink intercepted via either email or SMS device pairing. It contains your Taplytics URL scheme and device token. If you wish to intercept the deeplink and then pair the device yourself in your application's code, call this method in your app's LAUNCH activity or MAIN activity, like so:

private void handleDeepLink(Intent intent) {
    String tlDeeplink = intent.getDataString(); //example deep link: 'tl-506f596f://e10651f9ef6b'
    if (tlDeeplink == null) {
            return; // No deeplink found

Additionally, if you are using singleTop activities, you MUST handle the incoming intents in your activity like so:

protected void onNewIntent(Intent intent) {
    // this handles the intents in the case where your main activity has already been created

Do not forget to get your Taplytics URL Scheme from your Project's Settings:


Then, add it to your manifest in its own intent filter:

                <action android:name="android.intent.action.VIEW"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>
                <data android:scheme="YOUR URL SCHEME"/>

NOTE: The socketIO dependency must be present in the release build (ie not set to debugcompile) to pair with a release build.