Summary

The native Android SDK for Tenjin. To learn more about Tenjin and our product offering, please visit https://www.tenjin.com.

• Please see our Release Notes to see detailed version history of changes.
• We recommend using the latest version of Android Studio.
• For Unity integration, please visit https://github.com/tenjin/tenjin-unity-sdk.
• For any issues or support, please contact: support@tenjin.com

Table of contents

• Permissions
• SDK Integration
  • Google Play Services
  • OAID
    • MSA OAID
    • Huawei OAID
    • Huawei Install Referrer
  • Proguard
• Integration
  • App Initilization
  • App Store
  • GDPR
  • Purchase Events
  • Custom Events
  • Deferred Deeplink
  • App Subversion
• Testing

Permissions

The Tenjin SDK requires the following permissions:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- Required to get network connectivity (i.e. wifi vs. mobile) -->

Starting early 2022, the following permission is required to obtain Google advertising ID for apps with target API level set to 31 (Android 12). Please add this permission as soon as possible.

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

If you are using an Ad Network that targets the IMEI for the apps not on Google Play store, you will need to add the following permissions enabled. If you promote apps only on Google play store, you don't need to enable this permission.

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

SDK Integration

Android Studio

1. Download the latest Android SDK from here.
2. Add the Tenjin SDK into your Android Studio project by selecting: New > Module.
3. In the New Module dialog, select the Import .JAR.AAR Package option and click on Next.
   
   
   
   
4. Select the tenjin.jar or tenjin.aar file and click on Finish.
5. In your app module's build.gradle file, make sure to add this into the dependencies block:

dependencies {
  compile project(":tenjin")
}

Google Play Services and Install Referrer

If you are distributing your app with Google Play, you will need to add Google Play Services and Install Referrer libraries, add it to your build.gradle file.

dependencies {
  implementation 'com.google.android.gms:play-services-analytics:{version}'
  implementation 'com.android.installreferrer:installreferrer:{version}'
}

OAID and other Android App Stores

Tenjin supports promoting your app on other Android App Stores using the Android OAID. We have the following requirements for integrating OAID libraries. If you plan to release your app outside of Google Play, make sure to implement these OAID libraries.

MSA OAID

MSA OAID is an advertising ID for devices manufactured in China that the MSA (Mobile Security Alliance) provides. For integration with the MSA libary, download the following oaid_sdk_1.0.25.aar and supplierconfig.json.

Add the following to your project gradle file:

implementation files('libs/oaid_sdk_1.0.23.aar')

Be sure to copy the supplierconfig.json file to the assets folder of your project.

Set your App Store Type value to other:

TenjinSDK instance = TenjinSDK.getInstance(this, "<API_KEY>");

instance.setAppStore(TenjinSDK.AppStoreType.other);

Huawei OAID

For outside of China, you can collect OAID using the library provided by Huawei. For integration with the Huawei OAID libary, add the following to your project:

In your build.gradle file, add the Maven address for the Huawei SDKs:

allprojects {
    repositories {
        google()
        jcenter()
        maven { url 'https://developer.huawei.com/repo/' }
    }
}

dependencies {
    implementation 'com.huawei.hms:ads-identifier:{version}'
}

Set your App Store Type value to other:

TenjinSDK instance = TenjinSDK.getInstance(this, "<API_KEY>");

instance.setAppStore(TenjinSDK.AppStoreType.other);

Huawei Install Referrer

If you are marketing your app with Huawei App Gallery, add both the Huawei OAID SDK from above and the Install Referrer library.

dependencies {

    implementation 'com.huawei.hms:ads-identifier:{version}'
    implementation 'com.huawei.hms:ads-installreferrer:{version}'

}

Proguard Settings

-keep class com.tenjin.** { *; }
-keep public class com.google.android.gms.ads.identifier.** { *; }
-keep public class com.google.android.gms.common.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep class * extends java.util.ListResourceBundle {
    protected Object[][] getContents();
}
-keepattributes *Annotation*

If you are using Huawei libraries, you can to use these setttings:

-keep class com.huawei.hms.ads.** { *; }
-keep interface com.huawei.hms.ads.** { *; }

Integration

App Initialization

1. Get your <API_KEY> from your Tenjin dashboard.
2. In your Activity, import Tenjin: import com.tenjin.android.TenjinSDK;
3. In the onResume method of your main Activity class add the following line of code:

TenjinSDK instance = TenjinSDK.getInstance(this, "<API_KEY>");

instance.connect();

NOTE: Please make sure you implement this code on every onResume, not only on the first app open of the app. If we notice that you don't follow our recommendation, we can't give you proper support or your account might be suspended.

App Store

By default, Google Play is the default App Store. If you are publishing in a different App Store, update to the appropriate TenjinSDK.AppStoreType.* value:

1. AndroidManifest.xml:

<meta-data
    android:name="TENJIN_APP_STORE"
    android:value="{{APP_STORE_TYPE_VALUE}}" />

1. setAppStore():

TenjinSDK instance = TenjinSDK.getInstance(this, "<API_KEY>");

instance.setAppStore(TenjinSDK.AppStoreType.{{APP_STORE_TYPE_VALUE}});

Current AppStoreType options:

• googleplay
• amazon
• other

GDPR

As part of GDPR compliance, with Tenjin's SDK you can opt-in, opt-out devices/users, or select which specific device-related params to opt-in or opt-out. optOut() will not send any API requests to Tenjin and we will not process any events.

To opt-in/opt-out:

import com.tenjin.android.TenjinSDK;

public class TenjinDemo extends ActionBarActivity {

    @Override
    public void onResume() {
        //standard code
        super.onResume()

        //Integrate TenjinSDK connect call
        String apiKey = "<API_KEY>";
        TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

        boolean userOptIn = checkOptInValue();

        if (userOptIn) {
            instance.optIn();
        }
        else {
            instance.optOut();
        }

        instance.connect();

        //Your other code...
        //...

    }

    protected boolean checkOptInValue(){
        // check opt-in value
        // return true; // if user opted-in
        return false;
    }
}

To opt-in/opt-out specific device-related parameters, you can use optInParams() or optOutParams().

• optInParams() will only send device-related parameters that are specified. optOutParams() will send all device-related parameters except ones that are specified.

• Please note that we require the following parameter to properly track devices in Tenjin's system. If the mandatory parameter is missing the event will not be processed or recorded.

  • advertising_id

• If you are targeting IMEI and/or OAID Ad Networks, these params are required:

  • imei
  • oaid

• If you plan on using Google AdWords, these params are required:

  • platform
  • os_version
  • locale
  • device_model
  • build_id

If you want to only get specific device-related parameters, use optInParams(). In example below, we will only these device-related parameters: ip_address, advertising_id, limit_ad_tracking, and referrer.

String apiKey = "<API_KEY>";
TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

String[] optInParams = {"ip_address", "advertising_id", "limit_ad_tracking", "referrer"};
instance.optInParams(optInParams);

instance.connect();

If you want to send ALL parameters except specfic device-related parameters, use optOutParams(). In example below, we will send ALL device-related parameters except:

String apiKey = "<API_KEY>";
TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

String[] optOutParams = {"locale", "timezone", "build_id"};
instance.optOutParams(optOutParams);

instance.connect();

Device-Related Parameters

Purchase Events

To understand user revenue and purchase behavior, developers can send transaction events to Tenjin. Tenjin will validate transaction receipts for you. Please note that we currently only support IAP transactions from Google Play.

IMPORTANT: You will need to add your app's public key in the Tenjin dashboard > Your Android App > Edit. You can retreive your Base64-encoded RSA public key from the Google Play Developer Console > Select your app > Development Tools > Services & APIs.

After entering your Public Key into the Tenjin dashboard for your app, you can use the Tenjin SDK method below:

public void transaction(String productId, String currencyCode, int quantity, double unitPrice, String purchaseData, String dataSignature)

Example:

public void sendPurchaseEvent(Purchase purchase, Double price, String currencyCode) {
        String sku = purchase.getSku();
        String purchaseData = purchase.getOriginalJson();
        String dataSignature = purchase.getSignature();

        TenjinSDK instance = getTenjinInstance();
        instance.transaction(sku, currencyCode, 1, price, purchaseData, dataSignature);
}

You can verify if the IAP validation is working through our Live Test Device Data Tool. You should see a live event come in:

Disclaimer: If you are implementing purchase events on Tenjin for the first time, make sure to verify the data with other tools you’re using before you start scaling up you user acquisition campaigns using purchase data.

Custom Events

NOTE: The initialization event connect() must come before any custom events are sent.

You can use the Tenjin SDK to pass a custom event: eventWithName(String name).

The custom interactions with your app can be tied to level cost from each acquisition source that you use through Tenjin's service. Here is an example of usage:

String apiKey = <API_KEY>;
TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

//Integrate a custom event with a distinct name - ie. swiping right on the screen
instance.eventWithName("swipe_right");

Custom Events with values:

You can use the Tenjin SDK to pass a custom event with an integer value: eventWithNameAndValue(String name, String value) or eventWithNameAndValue(String name, int value).

Passing an integer value with an event's name allows marketers to sum up and track averages of the values passed for that metric in the Tenjin dashboard. If you plan to use DataVault, these values can be used to derive additional metrics that can be useful.

String apiKey = <API_KEY>;
TenjinSDK.instance = TenjinSDK.getInstance(this, apiKey);

//Integrate a custom event with a distinct name and value - ie. paying 100 virtual coins for an item
instance.eventWithNameAndValue("item", 100);

Using the example above, the Tenjin dashboard will sum and average the values for all events with the name item.

Keep in mind that this event will not work if the value passed not an integer.

Deferred Deeplink

Tenjin supports the ability to direct users to a specific part of your app after a new attributed install via Tenjin's campaign tracking URLs. You can utilize the getDeeplink method and callback to access the deferred deeplink through the data object. To test you can follow the instructions found here.

import com.tenjin.android.TenjinSDK;
import com.tenjin.android.Callback;

public class TenjinDemo extends ActionBarActivity {

    //...other callbacks are here

    @Override
    public void onResume() {
        //standard code
        super.onResume()

        //Integrate TenjinSDK connect call
        String apiKey = "<API_KEY>";
        TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);
        instance.connect();

        instance.getDeeplink(new Callback() {
            @Override
            public void onSuccess(boolean clickedTenjinLink, boolean isFirstSession, Map<String, String> data) {
                if (clickedTenjinLink) {
                    if (isFirstSession) {
                        if (data.containsKey(TenjinSDK.DEEPLINK_URL)) {
                           // use the deferred_deeplink_url to direct the user to a specific part of your app
                        }
                    }
                }
            }
        });

        //Your other code...
        ...

    }

Below are the parameters, if available, that are returned in the deferred deeplink callback:

You can also use the v1.7.1+ SDK for handling post-install logic by checking the isFirstSession param. For example, if you have a paid app, you can register your paid app install in the following way:

import com.tenjin.android.TenjinSDK;

public class TenjinDemo extends ActionBarActivity {

    //...other callbacks are here

    @Override
    public void onResume() {
        //standard code
        super.onResume()

        //Integrate TenjinSDK connect call
        String apiKey = "<API_KEY>";
        TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);
        instance.connect();

        instance.getDeeplink(new Callback() {
            @Override
            public void onSuccess(boolean clickedTenjinLink, boolean isFirstSession, Map<String, String> data) {
                if (isFirstSession) {
                  // send paid app price and revenue to Tenjin
                }
            }
        });

        //Your other code...
        ...

    }

App Subversion parameter for A/B Testing (requires DataVault)

If you are running A/B tests and want to report the differences, we can append a numeric value to your app version using the appendAppSubversion() method. For example, if your app version 1.0.1, and set appendAppSubversion(8888), it will report app version as 1.0.1.8888.

This data will appear within DataVault where you will be able to run reports using the app subversion values.

TenjinSDK instance = TenjinSDK.getInstance(this, "<API_KEY>");
instance.appendAppSubversion(8888);
instance.connect();

Testing

You can verify if the integration is working through our Live Test Device Data Tool. Add your advertising_id or IDFA/GAID to the list of test devices. You can find this under Support -> Test Devices. Go to the SDK Live page and send a test events from your app. You should see a live events come in: