Google Play Referrer API: Track and measure your app installs easily and securely

Posted by Neto Marin, Developer Advocate

Understanding how people find your app and what they do once they've installed it is crucial to helping you make the right product and marketing decisions. This is especially important when you're deciding your advertising strategy and budget. Today many app measurement companies and ad networks offer ad attribution solutions based on referral data. As such accurate install referral data is vital for correctly attributing app installs, as well as discounting fraudulent attempts for install credit.

To help you obtain more accurate and reliable data about your installs, we're introducing the Google Play Install Referrer API, a reliable way to securely retrieve install referral content. Using this API, your app will get precise information straight from the Play Store, including:

The referrer URL of the installed package.
The timestamp, in seconds, of when the referrer click happened.
The timestamp, in seconds, of when the installation began.

We've tested the API with our App Attribution Program partners including Adjust, AppsFlyer, Singular and TUNE.

"The new Play API provides us with the data we need to effectively detect and prevent click injection; it's a monumental step in securing a crucial information exchange on Android."

- Paul Müller, CTO & Co-Founder, Adjust

"The new Google Play API introduces fresh insights into both mobile ad fraud and the mobile user journey, two key domains with impact across the ecosystem."

- Elad Mashiach, VP, AppsFlyer

"Google's new API is a game changer that will help marketing analytics platforms like Singular identify and prevent a significant portion of Ad Fraud, and provide security and accuracy to mobile advertisers"

- Gadi Eliashiv, CEO & Co-Founder, Singular

"This new data from Google Play is essential for marketers who demand accountability out of their mobile app install advertising spend. At TUNE, this data is allowing us to outright eliminate entire forms of mobile app install fraud while providing new insight into how mobile app installs are driven."

– Dan Koch, Chief Technical Officer, TUNE

Starting today, the API works with the Play Store app from version 8.3.73 and later for all developers.

Play Install Referrer Library 1.0 now available

To make it easy to integrate the Install Referrer API, we've released the Install Referrer Library 1.0 for Android. The library is available in our Maven repository. To start using it, add the following dependency to your app module build.gradle file:

dependencies {
          ...
          compile 'com.android.installreferrer:installreferrer:1.0'
      }

All communication with the Play Store app happens through a Service, so the first step is to establish the connection between your app and the Play Store. Also, to receive the connection result and updates it's necessary to implement a listener, InstallReferrerStateListener. This listener could be your current Activity or any other class you want to use:

public class MainActivity extends AppCompatActivity 
    implements InstallReferrerStateListener {
    …
}

Now that you have an InstallReferrerStateListener, you can start binding your app to the Play Store app service. To establish the connection, you must build an InstallReferrerClient instance and call the startConnection() method:

InstallReferrerClient mReferrerClient
...
mReferrerClient = newBuilder(this).build();
mReferrerClient.startConnection(this);

Then, handle the connection result in the onInstallReferrerSetupFinished() method. If the connection is OK, the app can retrieve install referrer information, by calling the getInstallReferrer() method:

@Override
public void onInstallReferrerSetupFinished(int responseCode) {
   switch (responseCode) {
       case InstallReferrerResponse.OK:
           try {
               Log.v(TAG, "InstallReferrer conneceted");
               ReferrerDetails response = mReferrerClient.getInstallReferrer();
               handleReferrer(response);
               mReferrerClient.endConnection();
           } catch (RemoteException e) {
               e.printStackTrace();
           }
           break;
       case InstallReferrerResponse.FEATURE_NOT_SUPPORTED:
           Log.w(TAG, "InstallReferrer not supported");
           break;
       case InstallReferrerResponse.SERVICE_UNAVAILABLE:
           Log.w(TAG, "Unable to connect to the service");
           break;
       default:
           Log.w(TAG, "responseCode not found.");
   }
}

For more details about the new API and the client library, visit the Install Referrer Client Library page and the reference documentation.

Other Implementations

If you are not able to use our client library, you can use the AIDL interface and establish the connection with Google Play Store on your own. Check out the IGetInstallReferrerService AIDL reference for details of the methods and the service specification.