Handling New Installs using the Mobile Growth API on Android

Overview

With the Yozio Mobile Growth API you can attribute new installs and pass new install data to your app. This enables you to provide your users with highly personalized onboarding (e.g. deferred deep linking, auto-login, referrals, etc). Since Yozio offers 100% accurate options for both iOS and Android and gives you our exact confidence calculation with each transaction you can personalize with confidence.

Install Attribution on Android

For Android, you’ll need to choose one method to implement; using 100% methods in combination with fingerprint methods may cause install attribution inflation. If you are using Google Play market stores we recommend the Yozio Android 100% Matching API. If you’re focusing on the international market and promoting your app from non-Google Play Android marketplaces such as Baidu/Tencent/360 in China or wish to have Yozio handle the metadata passing rather than Google, the Yozio Fingerprint Matching API is perfect for you.

Yozio Fingerprint Matching API

With fingerprint matching, Yozio uses a variety of parameters that we collect when the install happens to calculate the likelihood that a particular click event was responsible for the new install later down the road.

To attribute an install made as a result of a click on a Yozio SuperLink using Fingerprint matching, make an HTTP POST to the endpoint https://api.yozio.com/v2.0/?method=install.attribution.metadata.get in the onCreate method of your Main or Launcher Activity. Additionally you’ll set the parameter "attribution_method" to “fingerprinting”. Here is a list of the required parameters needed to make a call to the Install Attribution Fingerprint Matching API:

Name Required Description Example Code
app_key Yes Log in Yozio Console, click "SDK" on the left sidebar and App Key and Secret Key is available at that page. 99e90a1a-f07a-42db-926d-0be333b726c6
secret_key Yes 3fc0caee-8bef-4ea0-a89e-919b5168a9e6
attribution_method Yes The method used to attribute the install back to the click. At this moment, only fingerprint matching is supported. All available values will be listed in the “Example” column. fingerprinting
os Yes Operating system. All available value will be listed in the “Example” column. android
os_version Yes Android version 5.1.1
android.os.Build.VERSION.RELEASE
hardware Yes Android device model Nexus 4
android.os.Build.MODEL

Additionally, there are optional parameters that may not be required, but will greatly improve the accuracy of the fingerprint match. Check out our API reference doc for a list of all the possible optional parameters.

On a successful call to this API, the response will contain whether or not a match was found, and if a match was found, the metadata associated with the Yozio SuperLink click event.

This call will also track the install if a match is found. There is no additional action required to track your install once a match is found; you can expect the Yozio Dashboard to reflect the new install event.

Here is a sample HTTP request containing the required parameters on iOS:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
public static HashMap<String, Object> getNewInstallMetadata(Context context) {

    if (!firstOpen(context)) {
        Logger.log(Logger.LOG_LEVEL.INFO, "getNewInstallMetadata - Not first open.");
        return new HashMap<String, Object>();
    }

    Logger.log(Logger.LOG_LEVEL.INFO, "getNewInstallMetadata - First open.");
    markOpened(context);

    List<YozioNameValuePair> getParams = new LinkedList<YozioNameValuePair>();
    getParams.add(new YozioNameValuePair("method", "install.attribution.metadata.get"));

    List<YozioNameValuePair> postParams = new LinkedList<YozioNameValuePair>();
    postParams.add(new YozioNameValuePair("app_key", APP_KEY));
    postParams.add(new YozioNameValuePair("secret_key", SECRET_KEY));
    postParams.add(new YozioNameValuePair("attribution_method", "fingerprinting"));

    // adding system info params to post params

    HashMap<String, String> deviceSystemInfo = SystemInfo.getInstance().getSystemDictionary(context);

    for (String key : deviceSystemInfo.keySet()) {
        String value = String.valueOf(deviceSystemInfo.get(key));
        postParams.add(new YozioNameValuePair(key, value));
    }

    // String response = doPostRequest(YOZIO_API_BASE_URL, getParams, postParams);
    return parseMetadata(response);
}

private static HashMap<String, Object> parseMetadata(String response) {

    try {
        JSONObject returnObj = new JSONObject(response);
        Map<String, Object> returnHash = Json.toMap(returnObj);

        if ("ok".equals((String) returnHash.get("status"))) {
            if (returnHash.get("body") instanceof HashMap) {
                @SuppressWarnings("unchecked")
                HashMap<String, Object> metadata = (HashMap<String, Object>) returnHash.get("body");

                // pass meta data back to the app
                return metadata;
            }
        }
    } catch (Exception e) {
        Logger.log(Logger.LOG_LEVEL.ERROR, "Response from server is invalid: " + e.getMessage());
    }
    return new HashMap<String, Object>();
}

Here is a sample of the JSON response made on a successful call to the Install Attribution API where a match has been found:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "status": "ok",
    "body": {
        "short_url": "tb.c.c",
        "probability": 0.7400948543818, // range [0,1]
        "timestamp": 1453404473338
        "metadata": { 
            "promo-code": "XXYYZZ",
            "referrer": "ZZYYXX",
        }
    }
}

For example JSON responses for when a match has not been found, or when the call is unsuccessful (due to missing parameters, or any other type of error), check out the API reference doc.

Yozio Android 100% Matching API

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.

This API requires the Google Play market. This API enables you to pass the metadata to Yozio which you got from the Google Play by receiving com.android.vending. INSTALL_REFERRER. This will enables you to achieve 100% accurate install attribution with Yozio SuperLink. This also means that you’ll be unable to use it for other marketplaces, such as Amazon, Samsung, or those in China like Baidu. For these marketplaces we suggest you use the Fingerprint Matching API.

Note: The 100% Matching using Google Play does not return any metadata (unlike the Fingerprint matching API, which returns a JSON entry containing all metadata associated with the attribution). You will need to parse the metadata out of the referrer string that you pass to the 100% Matching using Google Play API.

Setup

First, implement the BroadcastReceiver class. The onReceive method will take in a context and an intent. To retrieve the referrer string from the broadcast, simply call

1
intent.getStringExtra("referrer");

on the intent passed into the onReceive method of your BroadcastReceiver class. This will get the referrer string out of the intent, which will contain the entire referrer string that was passed to Google Play from the Yozio SuperLink, including any and all metadata that was attached to the SuperLink. You’ll pass this string to our API, and from there the API will handle the attribution. Specifically, we will look for the metadata key value pair __y=1; this piece of metadata indicates that the install was a result from a click on a Yozio SuperLink.

Note: intent.getStringExtra("referrer"); pulls the referrer string out of the Google Play new install broadcast. This referrer string will contain any and all metadata associated with the click on a Yozio SuperLink that resulted in the install. Check out the Data Passing over Deep Links on Android article for more information on parsing metadata.

Then, in the BroadcastReceiver class, make a call to our API (we recommend using an async task to do this).

To attribute an install made as a result of a click on a Yozio SuperLink using 100% matching, make an HTTP POST to the endpoint https://api.yozio.com/v2.0/?method=install.attribution.with.google.play.referrer in the onReceive method of your BroadcastReceiver implementation. Here is a list of the required parameters needed to make a call to the Install Attribution 100% Matching API using Google Play Broadcast:

Name Required Description Example Code
app_key Yes Log in Yozio Console, click "SDK" on the left sidebar and App Key and Secret Key is available at that page. 99e90a1a-f07a-42db-926d-0be333b726c6
secret_key Yes 3fc0caee-8bef-4ea0-a89e-919b5168a9e6
referer Yes Query string that been received from google play market which constructed by Yozio link, this query string will always include __y=1 __ysurl=g.c.c&__y=1&hello=world
hardware Yes Device model Nexus 9
android.os.Build.MODEL

Additionally, there are optional parameters that may not be required. Check out our API reference doc for a list of all the possible optional parameters.

Finally, add the following to your intent filter

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

This intent filter will send the new install broadcast made whenever an app is installed to your BroadcastReceiver implementation.

Verifying Install Attribution on Android

The easiest way to test if the install attribution is working correctly is to make an HTTP request to the API directly using an HTTP request tool, such as curl.

First, click on the Yozio SuperLink that you’d like to test using any iOS device. Make sure that you collect the system information needed in the API call.

These are the typical responses you should expect to see, and when you can expect to see them:

API call succeeds and finds a matched click on a Yozio SuperLink
{
    "status": "ok",
    "body": {
        "short_url": "tb.c.c",
        "timestamp": 1453404473338
        "metadata": { 
            "promo-code": "XXYYZZ",
            "referrer": "ZZYYXX",
        }
    }
}
API call fails
{
    "status": "error",
    "message": "[error message]" // format of error msg may change
}