lightbulb_outline Please take our October 2018 developer survey. Start survey

Play Install Referrer Library

You can use the Google Play Store's Install Referrer API to securely retrieve referral content from Google Play. The Play Install Referrer API Client Library is written in Java and is a wrapper for the Android Interface Definition Language (AIDL) file that defines the interface to the Install Referrer service. You can use the Play Install Referrer API Client Library to simplify your development process.

This guide covers the basics of retrieving referral information from Google Play using the Play Install Referrer Library.

Note: If you are using a language other than Java, or you want to interact directly with the AIDL file, use the Play Install Referrer API.

Updating your app's dependencies

Add the following line to the dependencies section of the build.gradle file for your app:

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

Connecting to Google Play

Before you can use the Play Install Referrer API Library, you must establish a connection to the Play Store app using the following steps:

  1. Call the newBuilder() method to create an instance of InstallReferrerClient class.
  2. Call the startConnection() to establish a connection to Google Play.

  3. The startConnection() method is asynchronous, so you must override InstallReferrerStateListener to receive a callback after startConnection() completes.

  4. Override the onInstallReferrerSetupFinished() method to handle lost connections to Google Play. For example, the Play Install Referrer Library client may lose connection if the Play Store service is updating in the background. The library client must call the startConnection() method to restart the connection before making further requests.

The following code demonstrates how to start and test a connection to the Play Store app:

Kotlin

private lateinit var mReferrerClient: InstallReferrerClient
...

mReferrerClient = InstallReferrerClient.newBuilder(this).build()
mReferrerClient.startConnection(object : InstallReferrerStateListener {

    override fun onInstallReferrerSetupFinished(responseCode: Int) {
        when (responseCode) {
            InstallReferrerResponse.OK -> {
                // Connection established
            }
            InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> {
                // API not available on the current Play Store app
            }
            InstallReferrerResponse.SERVICE_UNAVAILABLE -> {
                // Connection could not be established
            }
        }
    }

    override fun onInstallReferrerServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
})

Java

InstallReferrerClient mReferrerClient
...
mReferrerClient = InstallReferrerClient.newBuilder(this).build();
mReferrerClient.startConnection(new InstallReferrerStateListener() {
    @Override
    public void onInstallReferrerSetupFinished(int responseCode) {
        switch (responseCode) {
            case InstallReferrerResponse.OK:
                // Connection established
                break;
            case InstallReferrerResponse.FEATURE_NOT_SUPPORTED:
                // API not available on the current Play Store app
                break;
            case InstallReferrerResponse.SERVICE_UNAVAILABLE:
                // Connection could not be established
                break;
        }
    }

    @Override
    public void onInstallReferrerServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
});

Getting the install referrer

After you have established a connection to the Play Store app:

  1. Use the synchronized getInstallReferrer() method to return ReferrerDetails.

  2. Then, use methods in ReferrerDetails to get install timestamps and a referrer url.

The following code demonstrates how you can access the install referrer information:

Kotlin

val response: ReferrerDetails = mReferrerClient.installReferrer
response.installReferrer
response.referrerClickTimestampSeconds
response.installBeginTimestampSeconds

Java

ReferrerDetails response = mReferrerClient.getInstallReferrer();
response.getInstallReferrer();
response.getReferrerClickTimestampSeconds();
response.getInstallBeginTimestampSeconds();

Caution: The install referrer information will be available for 90 days and won't change unless the application is reinstalled. To avoid unecessary API calls in your app, you should invoke the API only once during the first execution after install. Your app can listen to the system broadcast Intent.ACTION_PACKAGE_FIRST_LAUNCH to identify the app's first execution. For details about how to handle a broadcast, check the Receiving broadcasts section.

Closing service connection

After getting referrer information, call the endConnection() method on InstallReferrerClient instance to close the connection. Closing the connection will help you avoid leaks and performance problems.

Refer to the Play Install Referrer Library Reference for further information.