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 the Java programming language 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 developing your app using a language other than the Kotlin programming language or the Java programming language, you can interact directly with the AIDL file by using the [Play Install Referrer
| API](https://developer.android.com/google/play/installreferrer/igetinstallreferrerservice).

## Updating your app's dependencies

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

### Groovy

```groovy
dependencies {
    ...
    implementation "com.android.installreferrer:installreferrer:2.2"
}
```

### Kotlin

```kotlin
dependencies {
    ...
    implementation("com.android.installreferrer:installreferrer:2.2")
}
```

## 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()`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient#newBuilder(android.content.Context)) method to create an instance of [`InstallReferrerClient`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient) class.
2. Call the
   [`startConnection()`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient#startConnection(com.android.installreferrer.api.InstallReferrerStateListener))
   to establish a connection to Google Play.

3. The [`startConnection()`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient#startConnection(com.android.installreferrer.api.InstallReferrerStateListener))
   method is asynchronous, so you must override
   [`InstallReferrerStateListener`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerStateListener)
   to receive a callback after
   [`startConnection()`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient#startConnection(com.android.installreferrer.api.InstallReferrerStateListener))
   completes.

4. Override the [`onInstallReferrerSetupFinished()`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerStateListener#onInstallReferrerSetupFinished(int))
   method to be notified when the callback completes. This method is called
   with a response code that you must use to handle the different states.
   [`OK`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient.InstallReferrerResponse#OK)
   indicates that the connection was successful. Each of the other
   [`InstallReferrerResponse`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient.InstallReferrerResponse)
   constants are for different types of errors.

5. Override the [`onInstallReferrerServiceDisconnected()`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerStateListener#oninstallreferrerservicedisconnected)
   method to handle lost connections to Google Play. For
   example, the Play Install Referrer Library client may lose the connection if the
   Play Store service is updating in the background. The library client must call
   the
   [`startConnection()`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient#startConnection(com.android.installreferrer.api.InstallReferrerStateListener))
   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

```kotlin
private lateinit var referrerClient: InstallReferrerClient

referrerClient = InstallReferrerClient.newBuilder(this).build()
referrerClient.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 couldn't be established.
            }
        }
    }

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

### Java

```java
InstallReferrerClient referrerClient;

referrerClient = InstallReferrerClient.newBuilder(this).build();
referrerClient.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 couldn't 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, get the details
from the install referrer by completing the following steps:

1. Use the synchronized
   [`getInstallReferrer()`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient#getInstallReferrer())
   method to return an instance of
   [`ReferrerDetails`](https://developer.android.com/reference/com/android/installreferrer/api/ReferrerDetails).

2. Use the methods that the
   [`ReferrerDetails`](https://developer.android.com/reference/com/android/installreferrer/api/ReferrerDetails)
   class provides to get details about the install referrer.

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

### Kotlin

```kotlin
val response: ReferrerDetails = referrerClient.installReferrer
val referrerUrl: String = response.installReferrer
val referrerClickTime: Long = response.referrerClickTimestampSeconds
val appInstallTime: Long = response.installBeginTimestampSeconds
val instantExperienceLaunched: Boolean = response.googlePlayInstantParam
```

### Java

```java
ReferrerDetails response = referrerClient.getInstallReferrer();
String referrerUrl = response.getInstallReferrer();
long referrerClickTime = response.getReferrerClickTimestampSeconds();
long appInstallTime = response.getInstallBeginTimestampSeconds();
boolean instantExperienceLaunched = response.getGooglePlayInstantParam();
```

**Caution:** The install referrer information will be
available for 90 days and **won't change** unless the application is
reinstalled. To avoid unnecessary API calls in your app, you should invoke the
API **only once** during the first execution after install.

## Closing service connection

After getting referrer information, call the
[`endConnection()`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient#endConnection())
method on your
[`InstallReferrerClient`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient)
instance to close the connection. Closing the connection will help you avoid
leaks and performance problems.

For further information, refer to the [Play Install Referrer Library
Reference](https://developer.android.com/reference/com/android/installreferrer/packages).