Actions

Android SDK2

From SVG Media

Contents

Introduction

Android SDK document is a set of instructions, which help a developer integrate TyrooSDK, so that it broadcasts an install event to Tyroo, if the install was initiated from Tyroo network. This results in a conversion being tracked in the platform and attributed to correct affiliate.

Basic Concepts

Android

Android 2.2 and higher allow a referrer variable to be passed in application links to Android Market. This variable is available during the app install process. This subsection briefly describes how to integrate TyrooSDK to track installs.

In all examples, we assume that our package is called com.coolapp.

Passing a referrer to Android Market

The format of a link to Android Market with a referrer valueis the following:

The referrer string must be URL-encoded; otherwise not all data may be passed correctly to the application.

Examples of URL below :


Workflow

SDK.png


Types of Campaign

Tracking Install Only

This option is used to track completion of install sequence of the app on android device. Configuring TyrooSdk into the app by-default tracks app installs.


Tracking first launch post Install

This option is used to track launch of the app post installation on an android device. To track first launch, instantiate a NTObject from Launcher Activity’s onCreate/onResume/onStart.

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_first);
    new NTObject(this);
}

Steps to configure SDK into the app

Incorporate SDK

  1. Download jar from Advertiser Sdk Jar
  2. Copy the jar into libs folder. OR
  3. Add and reference the Tyroo library project: Right click on your app project in Eclipse and select Build Path. Select Libraries tab -> Add external JARS -> Browse to Tyroo Phase 0 jar. Select “Order and Export” -> accept the check box next to Advertiser Jar to be exported into the application build.

Configure Tyroo Resource

Add/Create a resource file under res/values named “tyroo.xml" Create two resources named “tyroo_debug” and “uniqueId"

<resources>
    <bool name="tyroo_debug">true</bool>
    <string-array name="uniqueId">
        <item>IMEI</item>
    </string-array>
 </resources>


Tyroo resource file targets to configure advertiser app. These are advertiser configurable options..

  1. “tyroo_debug”: This is a Boolean resource which enables jar debugging. If set true then can see logs of url and response from tracking.

Syntax:

    <bool name="tyroo_debug">true</bool>
  1. “uniqueId”: This is a String array resource which configures unique key properties.

Syntax:

<string-array name="uniqueId">
    <item>MAC_ADDRESS</item>
    <item>IMEI</item>
</string-array>

In the above example there is a combination of 2 identifiers keys to be used as a unique key i.e. “MACID_IMEI”

Available options are

  1. CUSTOM
  2. IMEI
  3. IMSI
  4. BLUETOOTH
  5. ANDROID_ID(deviceId)
  6. MAC_ADDRESS

CUSTOM: Used if app wants to set its own kind of unique key over and above the options listed. This requires a to call NTObject.setUniqueCustomKey() from onCreate/onStart/onResume of Launcher Activity.

@Override
protected void onCreate(BundlesavedInstanceState) {
    super.onCreate(savedInstanceState);setContentView(R.layout.activity_first);
    new NTObject(this).setUniqueCustomKey(this, "test");
}

Call setUniqueCustomKey methods using NTObject and passing activity context and the unique key to be used as shown above.

Configure App for Broadcast

Add tyroo receiver in AndroidManifest.xml. Add the receiver tag under the application tag as follows:

<application android:allowBackup="true" android:icon="@drawable/ic_launcher"
            android:label="@string/app_name" android:theme="@style/AppTheme" >
    <activity android:name="com.tyroo.advertiser.sampleapp.FirstActivity" android:label="@string/app_name" >
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
    <receiver android:name="com.tyroo.sdk.TyrooReceiver" android:exported="true" >
        <intent-filter>
            <action android:name="android.net.conn.CONNECTIVITY_CHANGE"/>
            <action android:name="com.android.vending.INSTALL_REFERRER"/>
            <action android:name="TYROO_FIRST_LAUNCH"/>
        </intent-filter>
    </receiver>
</application>

Here we register Tyroo Broadcast receiver i.e. “com.tyroo.sdk.TyrooReceiver” for app install and connectivity change.

Add permissions to the App

<uses-sdk android:minSdkVersion="8"android:targetSdkVersion="18"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
  • "android.permission.READ_PHONE_STATE”: is added to get phone state like IMEI,Device id etc.
  • "android.permission.INTERNET” and “android.permission.ACCESS_NETWORK_STATE”: is added to open network socket in the app to send and receive data. And to read network properties like availability.
  • "android.permission.ACCESS_WIFI_STATE": is added to get wifi status.

Sequence of Actions for implementation

Step1: Provide the android app id to tyroo. We would pass a dynamic value in referrer(either directly or in utm_content) and this value needs to be passed back with during install.

Step2: We would share a test link with you, this can be used to test the application as well as to generate a sample click url.

Step3: You integrate the application, and run a test. This needs to be a complete flow test to ensure confirmation.

Step4: If it returns ‘Conversion Succeeded’, you can share the variables you hit and we can confirm. Once done, campaign goes live.

Step5: If it returns an error, please share the exact URL you are hitting, and we would check our logs and can recommend reasons for the same.

FAQs

What is "UniqueId" resource?

"UniqueId" is a resource of type String array defined in tyroo.xml. This defines which Unique Id to be picked for tracking transaction. This is set by the advertiser. This unique Id is passed as the transaction id for tracking.

Which is the recommended Unique Id?

MAC_ID is preferred in all available options as MAC_ID is unique for every device. And SDK assumes that data network is available from where the app has been downloaded.


What if “UniqueId” isn’t set in the tyroo.xml?

This is more like SDK not configured properly. So the sdk won’t work properly and no tracking will be tracked.

What if unique Id isn't available or failed reading

In cases where no unique Id is received… Current time's hashcode is used as the unique id.

How to fetch the unique Id used

Unique id used and referrer utm source can be fetched using getUniqueId() and getReferrerId() methods of NTObject class as below:

        NTObject ntObject = new NTObject(context);
        Log.d("Tyroo Keys", "referrer: " + ntObject.getReferrerId(this));
        Log.d("Tyroo Keys", "uniqueId: " + ntObject.getUniqueId(this));

What is “tyroo_debug” resource?

“tyroo_debug” is a resource of type Boolean used defined in tyroo.xml. This defines the debug state of SDK in advertiser app.


How to verify tracking?

Can enable “tyroo_debug” in advertiser app and filter device logs for “TYROO_PHASE0”. This will print logs on device console for the api hit and response received. Also tracking can be ensured via tyroo central login.


How to track app installs

Sdk looks for "_install_" key in the referrer string to track app install. So to track app install "_install_" key is to send as a part of referrer/utm_source.

I need to use GA at my end for tracking, can I still integrate both?

Absolutely, you can use GA. As mentioned earlier, if you intend to use GA, please follow instructions as mentioned in https://developers.google.com/analytics/devguides/collection/android/v2/campaigns

We would accordingly use utm_content to send our variable.

Handle Conversion tracking when using sdks from multiple/different Networks

As a single android app cannot have multiple receiver for same intent. Please refer this. https://developer.android.com/reference/com/google/android/gms/tagmanager/InstallReferrerReceiver.html

For these cases a new Broadcast Receiver is created in the app itself as below.

    public class AppReceiver extends BroadcastReceiver {
 
        @Override
        public void onReceive(Context context, Intent intent) {
            //Pass recived intent to all sdk receivers. As below
    	    new com.google.analytics.tracking.android.CampaignTrackingReceiver().onReceive(context, intent);
            new com.tyroo.sdk.TyrooReceiver().onReceive(context, intent);
        }
    }


Will Tyroo record all my installs?

No. Tyroo only record those installs, where the click originated from Tyroo network. Ideally, we suggest you fire our tag conditionally, i.e. only if utm_src specifies tyroo. If that's not possible, it is still not an issue, as we will not record anything which does not belong to us.

How to validate tracking ?

Upload apk on play store in as alpha version. Add people to your test group. Please refer below for more details "https://support.google.com/googleplay/android-developer/answer/3131213?hl=en"

Resources

Advertiser Sdk Sample App