Skip to content

Most visited

Recently visited


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 ''

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:

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

    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:

ReferrerDetails response = mReferrerClient.getInstallReferrer();

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.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields


Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience. (Dec 2017 Android Platform & Tools Survey)