Handling New Installs on Android

Overview

In this article, we’ll go over how to set up the Yozio SDK in your app to handle users who have just installed your app through a Yozio SuperLink.

The New Install of Yozio SuperLinks covers users who do not have your app and click on a Yozio SuperLink. There are a number of ways you can handle the users who do not have your app, but the new install case can be divided into two core pieces of functionality:

  • Install Attribution
  • Data passing

Prerequisites

  • Have the Yozio SDK added to your app
  • Have access to the Yozio Console for your SuperLinks
  • Have internet permissions enabled in your app. For Android, add the following line to your Manifest file, under the <application> tag:
1
<uses-permission android:name="android.permission.INTERNET" />

Install Attribution on Android

The first part of handling users who do not have the app is attributing installs to a click on a Yozio SuperLink that happened earlier. This is the most important step, as the tracking and data passing cannot occur without a correct attribution. We tie installs to clicks using a unique identifier for the SuperLink, the short URL (e.g. a.b.c is the short URL for r.rivendell.com/a.b.c), so that you can track on our Yozio Dashboard the activity on your SuperLinks and the campaigns that they represent.

Attribution using the Android SDK

Since the Google Play store allows for data passing into the app during a new install, we can be 100% confident when an install occurs from a Yozio SuperLink. When a user without your app clicks on a Yozio SuperLink, they will be redirected to the Google Play Store. Yozio will attach any metadata you’ve attached to the Yozio SuperLink and attach it to the Google Play URL. Yozio will also attach some internal flags that indicates that the app install came from a Yozio SuperLink.

Note: Need to track attribution for non-Google Play stores? We have a solution for that! Email us at [email protected] and we'll hook you up!

100% Matching using Google Play Broadcast

First, configure your Android Manifest file to register your app key and secret key. Add the following lines to your manifest file, under the <application> tag

1
2
<meta-data android:name="YozioAppKey" android:value="your-app-key" />
<meta-data android:name="YozioSecretKey" android:value="your-secret-key" />

Then, implement the MasterInstallReferrerReceiver class. We recommend implementing a “master” class that handles all new install broadcast receivers. When a new install broadcast is made, you must call Yozio’s broadcast receiver first to ensure that the new install is tracked properly. In this class, you’ll call the YozioReferrerReceiver.onReceive(context, intent) function. This function will run an async task that will wait for the new install broadcast (which can take anywhere up to many seconds to return) and track the new install once it receives it. Here is a sample implementation:

1
2
3
4
5
6
7
public class MasterInstallReferrerReceiver extends BroadcastReceiver{
    @Override
    public void onReceive(Context context, Intent intent) {
        YozioReferrerReceiver yozioReferrerReceiver = new YozioReferrerReceiver();
        yozioReferrerReceiver.onReceive(context, intent);
    }
}

Finally, configure your app to receive the broadcast that Google Play will send when a new install is made. Add the following lines to your manifest file, under the <application> tag

1
2
3
4
5
<receiver android:name="com.YOUR.PACKAGE.MasterInstallReferrerReceiver"  android:exported="true">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

Verifying New Install Attribution on Android

To verify new install handling on Android, simulate a Google Play new install broadcast. You can do this in one of two ways:

Upload the app to Google Play Staging and install the app from the Google Play Store

Click on a Yozio SuperLink and download the app from the Google Play Store.

Simulate a Google Play broadcast using adb.

Install the app through the IDE of your choice, and open the app. Then run the following commands:

1
2
adb shell          // make sure the adb tool is in your PATH
am broadcast -n com.YOUR.PACKAGE/YOUR_PACKAGE -a com.android.vending.INSTALL_REFERRER --es "referrer" "__y=1&__ysurl=test_short_url_would_be_here&your_metadata=would_be_here"

This will create a new install broadcast and send it to your app. (When you click on a Yozio SuperLink, we will attach a referrer string to the Google Play URL, which will then be passed into the app. This referrer string will tell the app that the install came from a Yozio SuperLink, __y=1, and which SuperLink it was, __ysurl=test_short_url_would_be_here. If your SuperLink is r.yozio.com/a.b.c, your short URL would be a.b.c. Using the adb command bypasses this process and passes a referrer string directly to the app). Note that this method of testing will post an install directly to our dashboard; if you don’t have many clicks on the Yozio SuperLink that corresponds to the test short URL you provide, you may see your install numbers be greater than your click numbers.

After you’ve simulated a Google Play new install broadcast, you should see the following logs:

1
2
3
YozioApi - sdkAppInstallAndroidWithReferrerApi - Post response: {"status":"ok","body":{"timestamp":xxxxxxxxxxxxx}}
YozioReferrerReceiver - Intent:Intent { act=com.android.vending.INSTALL_REFERRER flg=0x10 cmp=com.YOUR_APP/.util.MasterInstallReferrerReceiver (has extras) }
Got referrer string:__y=1&__ysurl=test_short_url_would_be_here&your_metadata=would_be_here

New Install Data Passing on Android

Passing data into the app after a new install occurs independently of tracking, but can only be done after an attribution has been made. Once Yozio knows a particular install event is tied with a click event, the metadata associated with the click can be properly parsed. As such, you will need to implement Install Attribution before implementing Data Passing into the app.

Implementing Data Passing using the Android SDK

If you’ve successfully implemented Install Attribution (using 100% matching using Google Play Broadcast) on Android, the YozioReferrerReceiver will make an async task that will parse the metadata when it receives the new install broadcast. We’ve provided an interface in our Android SDK called YozioMetaDataCallbackable that will be called by this async task once the metadata has been parsed. Implement this interface to handle new install metadata.

Here is a sample implementation of this interface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
public class YozioNewInstallMetaDataCallback implements YozioMetaDataCallbackable {

    public YozioNewInstallMetaDataCallback() {}

    public void onCallback(Context context, String targetActivityClassName, HashMap<String, Object> metaData) {

        if (targetActivityClassName != null) {
            Yozio.startActivityWithMetaData(context, targetActivityClassName, metaData);    
        } else {
            Yozio.startActivityWithMetaData(context, LauncherActivity, metaData);
        }
    }
}

The targetActivityClassName here is the target activity you provide in your SuperLink settings. To set this, go to the Yozio Console > SuperLinks > Edit (the SuperLink you are using) > Advanced Settings > Android Target Activity Class Name.

Once you’ve implemented this interface, add the following to your manifest file under the <application> tag:

1
<meta-data android:name="YozioNewInstallMetaDataCallback" android:value="com.YOUR_PACKAGE.YozioNewInstallMetaDataCallback" />

Then, call Yozio.initialize(context) in the onCreate method of your Main/Launcher activity. This will initialize the Yozio directory, which is required for persisting metadata. Here is some sample code demonstrating the correct way to call Yozio.initialize(context):

1
2
3
4
5
6
7
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Basic Yozio initialization
    Yozio.initialize(this);
}

Finally, when the broadcast receiver receives the new install broadcast, the new install metadata will be persisted locally on the device, and it will forever (as long as the user does not uninstall the app) be available for your app to use. Call the functions:

1
2
Yozio.getInstallMetaDataAsHash(context)
Yozio.getInstallMetaDataAsUrlParameterString(context)

to access it.

Verifying New Install Data Passing on Android

See “Verifying New Install Attribution on Android” for instructions on simulating a Google Play Broadcast.

To test, you will need to simulate a Google Play new install broadcast.

Simulating using Google Play Staging

Set the Android Target Activity Class Name if you are testing flow that will use this Activity. Simply click on the SuperLink and download the staging app.

Simulating using adb command

If you are using the adb command, add the key value pair __yta=ANDROID_TARGET_ACTIVITY_CLASS_NAME to the referrer string. Here is an example:

1
2
adb shell
am broadcast -n com.YOUR.PACKAGE/YOUR_PACKAGE -a com.android.vending.INSTALL_REFERRER --es "referrer" "__y=1&__ysurl=test_short_url_would_be_here&__yta=TARGET_ACTICITY_CLASS_NAME&your_metadata=would_be_here"

You’ll be looking for the following logs:

1
2
3
Got referrer string:__yta=com.YOUR.PACKAGE.TARGET_ACTIVITY_CLASS&__y=1&__ysurl=test_short_url_would_be_here&your_metadata=would_be_here"
parseQueryStringToHashMap - queryString is __yta=com.YOUR.PACKAGE.TARGET_ACTIVITY_CLASS&__y=1&__ysurl=test_short_url_would_be_here&your_metadata=would_be_here
parseQueryStringToHashMap - keyValuePairs is {__ysurl=test_short_url_would_be_here, __y=1, __yta=com.YOUR.PACKAGE.TARGET_ACTIVITY_CLASS, your_metadata=would_be_here}

to know that the new install metadata has been properly parsed.