Unliche SDK – Android documentation

Last Updated On January 03, 2019
< Back

 

Getting started
Unliche SDK helps you to track application installs and custom events.
We developed Unliche SDK to integrate easily and lightweight.

 

1. Embedding the SDK into Your Application (Mandatory)
The following steps are mandatory to measure installs and sessions. You can integrate the Unliche SDK automatically using Gradle’s Dependency Management.

 

1.1 Add the Unliche SDK to your Project
The simplest way to integrate the SDK into your project is by using Gradle’s Dependency. Adding Unliche’s Android SDK Dependency:

  1. Open your project (or create a new project), and then open your_app -> build.gradle
  2. Add this to Module-level /app/build.gradle before dependencies:
    repositories {
            mavenCentral()
    }
  3. Add the compile dependency with the latest version of the Unliche SDK in the build.gradle file:
    dependencies {
            compile 'com.rappier.unlichesdk:unlicheSDK:version_code+@aar'
    }

version_code is latest version

 

1.2 Set the Required Permissions

  • The AndroidManifest.xml should include the following permissions:
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  • ACCESS_WIFI_STATE and READ_PHONE_STATE permissions are optional.
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />

    Adding this permission enables the carrier to track IMEI.


1.3 Request permissions for Android version marshmallow and above
If your app needs permissions that were listed in the app manifest, it must ask the user to grant the permission. In our case, must ask permission of READ_PHONE_STATE. to integrate permission refer this

Note:
If you don’t provide this permission, then this leads to be data inconsistency in back-end.

 

1.4 Set an Install Referrer Broadcastreceiver in AndroidManifest.xml
receiver: Unliche SDK provides a solution that broadcasts INSTALL_REFERRER to all other receivers automatically. In the AndroidManifest.xml, add the following receiver as the FIRST receiver for INSTALL_REFERRER, and ensure the receiver tag is within the application tag:

<receiver android:name="com.rappier.unlichesdk.unlichelib.mainsdkclasses.TrackerEventReceiver" 
android:exported="true">
        <intent-filter>
                <action android:name="com.android.vending.INSTALL_REFERRER" />
        </intent-filter>
</receiver>

 

1.5 Embed Google Play Services into Your App

Collecting the Google Advertising ID (GAID) is essential for tracking campaigns across several channels including Facebook, Google and Twitter. To add Google Advertising ID:

Install the Google Play Services SDK and import it into your project. Add the following entry to the AndroidManifest.xml as the last entry under application (before </application>):
<meta-data android:name="com.google.android.gms.version"android:value="@integer/google_play_services_version" />

OR add following in build.gradle to avoid multidex exception:

dependencies {
        compile 'com.google.android.gms:play-services-ads:google_play_services_version'
}

Note:

  • Unliche uses the Google Play Services library for retrieving the Google Advertising ID.
  • Google Play Services 7.5 is the minimum requirement for the GCM Registration Token (which is used for our Uninstall measurement). Unliche recommends to always use the latest version.

 

2. SDK Initialization and Installation Event (Minimum Requirement for Tracking)

Note
This is the minimum requirement to begin tracking your app installs.

2.1 Initializing the SDK
To initialize the SDK, add the following code to your Application’s onCreate function:

Unliche.initEvent(Context context, String AccessToken, String mode);
  • context – use getApplicationContext()
  • AccessToken – is token used to otherize advertiser.
  • mode will be Unliche.LIVEMODE or Unliche.TESTMODE


Note:
AccessToken will get while register on portal of Unliche for tracking. If not already register then click here to register.
This API enables Unliche to detect installations, sessions, and updates.
Mode is used to test events in test mode while integrate Unliche with the application, Otherwise that should be live mode for production application.

 

2.2 Reporting Background Sessions
If your app is a utility app running in the background you can use the API as described in here to measure sessions and retention within Unliche.

3. In-App Events Tracking API (Optional)
There are two types of optional events contains in Unliche sdk, 1) Sdk defined 2) Custom events

3.1 Unliche Sdk Defined Events
This API enables Unliche to track some in app events that are already defined in sdk. App just need to call the methods of event and use it with specific events.

Events

3.1.1 Open
For user retention you have to include this event

Syntax:
Unliche.setOpenEvent(Context context);

  • context – use getApplicationContext()

 

To call event with category include below
Syntax:

Unliche.setOpenEvent(Context context, String category)
  • context – use getApplicationContext()
  • category – Category name that is created  while create campaign in Unliche system.

 

3.2 Custom events(Advertiser defined events)
This API enables Unliche to track post install events. These events are defined by the advertiser and include an event id, in addition to optional event values. Tracking in-app events helps you measure and analyze how loyal users discover your app, and attribute them to specific campaigns/media sources.

Syntax:

Unliche.setCustomEvent(Context context, int customEventId);
  • context – use getApplicationContext().
  • customEventId – event id generated while create custom event in Unliche system

 

Syntax:

Unliche.setCustomEvent(Context context, int customEventId, String additionalParam1, String additionalParam2, 
String additionalParam3, String additionalParam4, String additionalParam5);
  • context – use getApplicationContext().
  • customEventId – event id generated while create custom event in Unliche system
  • additionalParam1 to additionalParam5 – additional parameters which are advertiser wants to provide from app. Any parameter can be null.

 

To call above events with category include below

Syntax:
Unliche.setCustomEvent(Context context, int customEventId, String category);

  • context – use getApplicationContext().
  • customEventId – event id generated while create custom event in Unliche system
  • category – Category name that is created  while create campaign in Unliche system.

Syntax:

Unliche.setCustomEvent(Context context, int customEventId, String category, String additionalParam1, 
String additionalParam2, String additionalParam3, String additionalParam4, String additionalParam5);
  • context – use getApplicationContext().
  • customEventId – event id generated while create custom event in Unliche system
  • category – Category name that is created  while create campaign in Unliche system.
  • additionalParam1 to additionalParam5 – additional parameters which are advertiser wants to provide from app. Any parameter can be null.

 

Important Note for calling threads in the background:
If you want to call any of the Unliche method in the background thread, then it must be called in runOnUiThread method.

Syntax:

runOnUiThread(new Runnable() {
    @Override
    public void run() {
        // Call method here
    }
});

 

4. Optional fields to provide
There are some optional parameter you can provide.

4.1 User ID
Syntax:
Unliche.setUserId(String userId);

 

4.2 User name
Syntax:
Unliche.setUserName(String  username);

 

4.3 User phone number
Syntax:
Unliche.setPhoneNumber(String phoneNumber);

 

5. Uninstalls
To track uninstalls you have to integrate GCM/FCM in your app. Register app to GCM with project number and provide GCM token to below function.
To integrate GCM/FCM in app click here

Syntax:
Unliche.setUninstallEvent(Context context, String GCMToken);

  • context – use getApplicationContext().
  • GCMToken – is token provided by GCM/FCM to client.

 

6. Enable tracking Deep Linking
Note:

We highly recommend to have Deep Linking integrated in your app. Deep Linking is a crucial part of retargeting campaigns and it is highly recommended to use when running retargeting campaigns. for more information about deeplinking implementation in Android, Please check here.
Activities that are meant to be opened by deep linking should have the below intent filter on the activity definitions in the manifest file.

<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="https"
       android:host="t.unlc.co"
       android:pathPrefix="/camp_c" />
</intent-filter>

 

Same snippet will get when enable deep-link from advertiser panel.
Put following code on respective activity oncreate() method on which you have put above intent-filter.

Syntax:

if (getIntent().getData() != null){
    Unliche.sendRetagratingData(Context context);
}

 

To call same event with category,
Syntax:

if (getIntent().getData() != null){
    Unliche.sendRetagratingData(Context context, String category);
}
  • category – Category name that is created  while create campaign in Unliche system.

 

7. In-App Events Tracking Testing
If you want to test the events firing properly or not, you can test it by doing below steps.

  1. Login to Unliche and define the events within your application.
  2. Integrate the custom event tracking code in your application.
  3. Navigate to “Event integration” section under “Technical Config: from left menu panel.
  4. Then select the application and click on ‘Validate now’ button for each event.
  5. The “Status” should be “Successful” for a successful integration.
  6. If the “Status” is “Failed”, please check the integration again.

 

8. Standalone APP/APK
You can track app that is out of store in Unliche, For that follow following steps.

 

8.1 Advertiser portal
1. Register and Login in Unliche system as advertiser
2. While creating new application select standalone APK option.
3. Enter package name, socket and app URL (Form which apk will download directly), all params should be unique. Click to create app and complete process.
4. Note that, socket name is needed at the time of Android app integration.

 

8.2 Android application
1. Integrate Unliche SDK in your app as per SDK documentation.
2. In addition add following meta-data tag in your androidmanifest file under application tag.

Syntax:

<meta-data android:name="UNLICHE_SOCKET" android:value="TEST_SOCKET"/>

 

Note
TEST_SOCKET will be your unique socket name, that you already provided while creating app in advertiser portal.
3. Specify your Unliche SDK events in your application. (Default events are install and open which will call after installing and opening app)

 

8.3 Testing
1. Click on app URL that will download APK in your device.
2. Install downloaded APK.
3. Do the activities according to events and observe result in advertiser portal. By just opening app you can see install and open events data in advertiser portal.