Play Install Referrer Library

您可以使用 Google Play 商店的 Install Referrer API，即可從 Google Play 中安全地擷取參照內容。Play Install Referrer API 用戶端程式庫採用 Java 程式設計語言編寫，是 Android 介面定義語言 (AIDL) 檔案的包裝函式，可定義 Install Referrer 服務的介面。您可以使用 Play Install Referrer API 用戶端程式庫來簡化開發流程。

本指南說明使用 Play Install Referrer 程式庫從 Google Play 擷取參照資訊的基礎知識。

更新應用程式的依附元件

請在應用程式的 build.gradle 檔案的依附元件區段中新增以下這行：

Groovy

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

Kotlin

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

連結至 Google Play

您必須先按照下列步驟與 Play 商店應用程式建立連線，才能使用 Play Install Referrer API 程式庫：

  1. 呼叫 newBuilder() 方法來建立 InstallReferrerClient 類別的執行個體。

  2. 呼叫 startConnection() 建立與 Google Play 的連線。

  3. startConnection() 是非同步方法，因此您必須覆寫 InstallReferrerStateListener。 之後才接收回呼 startConnection() 完成。

  4. 覆寫 onInstallReferrerSetupFinished() 方法，以便在回呼完成時收到通知。您須使用回應代碼呼叫此方法來處理不同的狀態。OK 表示連線成功。其他的 InstallReferrerResponse 常數用於不同的錯誤類型。

  5. 覆寫 onInstallReferrerServiceDisconnected() 方法以處理與 Google Play 連線中斷的問題。例如，如果 Play 商店服務在背景進行更新，Play Install Referrer 程式庫用戶端可能會斷線。程式庫用戶端必須呼叫 startConnection() 方法重新啟動連線，才能再提出其他請求。

以下程式碼示範如何啟動並測試與 Play 商店應用程式的連線：

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

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.
    }
});

取得安裝參照網址

與 Play 商店應用程式建立連線後，請完成下列步驟，以取得安裝參照網址的詳細資料：

  1. 使用已同步的 getInstallReferrer() 方法傳回 ReferrerDetails 的執行個體。

  2. 使用 ReferrerDetails 類別的方法取得安裝參照網址的詳細資料。

以下程式碼示範如何存取安裝參照網址的資訊：

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

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

注意：安裝參照網址資訊的有效期為 90 天，而且除非使用者重新安裝應用程式，否則不會改變。為避免應用程式中發出不必要的 API 呼叫，在安裝完成後第一次執行時，請叫用 API 一次即可。

關閉服務連線

取得參照資訊後，請在 InstallReferrerClient 執行個體上呼叫 endConnection() 方法以關閉連線。關閉連線有助於避免資料外洩和效能問題。

詳情請參閱「Play Install Referrer 程式庫參考資料」。