Migrating from Android’s BroadcastReceiver to Google Play Install Referrer API with Adobe Analytics

frederikwerner profile image Frederik Originally published at frederikwerner.de on ・4 min read

Adobe Analytics can track not onlywebsites, but mobile apps just the same. This is achieved by using the Adobe Experience Platform Mobile SKDsfor native iOS and Android apps.

One very interesting part of trackingmobile apps is known as acquisition tracking, which looks at how users foundthe tracked app. To help with this, Adobe exposes some functionality in theirSDKs to listen for the events that the mobile operating system is using to tellapps about the way they have been installed. This happens “automagically” oniOS but needs some custom implementation on Android.

BroadcastReciever and Install Referrer API on Android

Adobe requires to use a very old implementation method called BroadcastReceiver. That method relies on the Google Play Store App sending a message (a broadcast) to the app that has just been installed, telling it about the details of the install (like which marketing campaign has been used). This is a very old method on Android and has a successor called Install Referrer API since 2017. Because of this Google announced to retire the old method by March 1, 2020 back in November 2019 and started sending out reminder emails.

By this date the Google Play Store App will stop sending out the broadcasts the Adobe SKDs rely on. This will only happen in newer versions of the Play Store App. As long as the user does not update that app, broadcasts will still be sent. If the old versions of the Play Store remain functional users could still install apps and the Play Store will send the broadcasts.

That portion of users will decrease withupdates over time but leaves marketeers with a scenario where both old and newmethods will be used. However, the good message is that there is no harm instill having the old code in your app, since it will only listen for abroadcast it will never receive.

As a migration strategy, app maintainerscould implement both methods. But this is not a good idea, since it would leaveus with two events for the same install. Because the new method has been aroundsince 2017, we can expect a high adoption by now. Therefore, we should onlyfocus on the state-of-the-art method.

New Adobe methods for Install Referrer

Adobe announced in the Experience Cloud Release Notes that a new version of the Mobile Services and Mobile SDKs will be released on January 16, 2020. The notes say:

  • Acquisition– Added a new API, Analytics.processGooglePlayInstallReferrerUrl(finalString url) , to support Google PlayInstall Referrer APIs.

At time of writing, those new versions arenot available for download via Mobile Services or GitHub.There is no documentation as well, so we need to make an educated guess at whatwe need to do.

The parameter of that new API gives us a hint. “final String url” looks like the string we would get when using the getInstallReferrer() method with the Install Referrer API. Given that information, let’s implement the new method with our Adobe SDKs!


The Adobe-official way of implementation might differ in the future. Also, those changes should not be made without the new SDK version available, since the old version does not have the API we need. This post was written on January 15, 2020, and things might have changed already.

Implementing Play Install Referrer with Mobile Services

The general method of implementing the newAPI is described in detail in the AndroidDeveloper Documentation. It involves connecting to Google Play to get thedesired information and handling the response.

But there is one caveat: The informationabout the install method remains available for 90 days after the installation.Because of this, we need to implement a different broadcast receiver (there itis again!) to only send the referrer on the first app launch. Since I am noAndroid developer, I will rely on MartinZeitler’s post on stackoverflow about how to implement this in conjunctionwith the olddocumentation.

To use the new Play API, we need to add thedependency to our build.gradle:

implementation 'com.android.installreferrer:installreferrer:1.1'

The next step is similar to the oldbroadcast receiver. In our AndroidManifest.xml, we replace the old

<receiver android:name="com.your.package.name.GPBroadcastReceiver" android:exported="true"> 
        <action android:name="com.android.vending.INSTALL_REFERRER" /> 


<receiver android:name="com.your.package.name.PackageStatusReceiver" android:exported="true"> 
        <action android:name="android.intent.action.PACKAGE_FIRST_LAUNCH" /> 

to get a notification about the firstlaunch of our app.

Next, in our PackageStatusReciever.java, we listen for that notification and pass it to the new Mobile Services API (might have missed some imports):

import com.adobe.mobile.*;
import android.content.BroadcastReceiver;
import com.android.installreferrer.api.InstallReferrerClient;
import com.android.installreferrer.api.InstallReferrerStateListener;
import com.android.installreferrer.api.ReferrerDetails;
import android.content.Context;
import android.content.Intent;

public class PackageStatusReceiver extends BroadcastReceiver implements InstallReferrerStateListener {

    protected static final String LOG_TAG = PackageStatusReceiver.class.getSimpleName();

    private InstallReferrerClient referrerClient;

    public void onReceive(Context context, Intent intent) {
        if(intent.getAction() != null) {
            if(intent.getAction().equals(Intent.ACTION_PACKAGE_FIRST_LAUNCH)) {
                this.referrerClient = InstallReferrerClient.newBuilder(context).build();

    public void onInstallReferrerSetupFinished(int responseCode) {
        switch (responseCode) {
            case InstallReferrerClient.InstallReferrerResponse.OK:
                Log.d(LOG_TAG, "InstallReferrer Response.OK");
                try {
                    ReferrerDetails response = referrerClient.getInstallReferrer();
                    String referrer = response.getInstallReferrer();
                    Log.d(LOG_TAG, "InstallReferrer " + referrer);
                } catch (RemoteException e) {
                    Log.e(LOG_TAG, "" + e.getMessage());
            case InstallReferrerClient.InstallReferrerResponse.FEATURE_NOT_SUPPORTED:
                Log.w(LOG_TAG, "InstallReferrer Response.FEATURE_NOT_SUPPORTED");
            case InstallReferrerClient.InstallReferrerResponse.SERVICE_UNAVAILABLE:
                Log.w(LOG_TAG, "InstallReferrer Response.SERVICE_UNAVAILABLE");
            case InstallReferrerClient.InstallReferrerResponse.SERVICE_DISCONNECTED:
                Log.w(LOG_TAG, "InstallReferrer Response.SERVICE_DISCONNECTED");
            case InstallReferrerClient.InstallReferrerResponse.DEVELOPER_ERROR:
                Log.w(LOG_TAG, "InstallReferrer Response.DEVELOPER_ERROR");

    public void onInstallReferrerServiceDisconnected() {
        Log.w(LOG_TAG, "InstallReferrer onInstallReferrerServiceDisconnected()");

Now, Mobile Services should receive thedata, since we called com.adobe.mobile.Analytics.processGooglePlayInstallReferrerUrl(referrer)with our referrer-string.

The post Migrating from Android’s BroadcastReceiver to Google Play Install Referrer API with Adobe Analytics appeared first on Frederik Werner's Website.

Posted on by:

frederikwerner profile



Data Scientist roaming the realms of Web Analytics and Online Marketing Tech


markdown guide