Google Play 內嵌安裝 (第三方應用程式商店)

本頁說明已註冊「目錄存取」計畫的第三方應用程式商店，如何整合 Google Play 內嵌安裝功能。這項功能可讓美國的第三方 Android 應用程式商店，將使用者導向至 Google Play 下載 Play 應用程式，且適用條款與直接透過 Google Play 商店進行的其他所有下載相同。

必要條件

在第三方應用程式商店中整合內嵌安裝 API 前，請務必先在 Google Play 管理中心完成下列設定：

  1. 加入 Play 目錄存取計畫：按照註冊說明操作。
  2. 選擇加入目錄存取計畫：透過 Play 管理中心設定加入目錄存取計畫。
  3. 擷取傳送權杖：處理提供給您的 Play 應用程式目錄匯出資料。這個匯出項目包含您有權發布的每個應用程式所需的 catalog_token (發布權杖)。

需求條件

如要讓使用者順利看到半頁介面，必須符合下列規定：

  • 使用者必須位於美國。
  • 裝置的 Google Play 版本必須至少為 52.3。
  • Android API 級別必須為 24 以上。
  • 如要存取 Play 商店，必須提供有效且未過期的 catalog_token。

從應用程式商店叫用內嵌安裝功能

如要叫用內嵌安裝半頁畫面，請建立 Intent 類別的執行個體，該執行個體會以 Google Play 深層連結網址為目標，並包含專屬的 catalog_token。

請參考下列程式碼範例 (Kotlin 或 Java)：

Kotlin

val intent = Intent(Intent.ACTION_VIEW)
val referrer = "<Your referrer string>"
val id = "<Package name of the app to be installed>"
val callerId = "<Package name of your third-party app store>"

// Retrieve the app-specific token from your processed catalog export
val catalogToken = getVerificationTokenByDocId(id)

intent.setPackage("com.android.vending")
val deepLinkUrl = "https://play.google.com/d?id=$id&referrer=$referrer"
intent.data = Uri.parse(deepLinkUrl)

// Set the required intent extras
intent.putExtra("overlay", true)
intent.putExtra("callerId", callerId)
intent.putExtra("catalog_token", catalogToken)

val packageManager = context.getPackageManager()
if (intent.resolveActivity(packageManager) != null) {
  startActivityForResult(intent, 0) // Call with a request code to receive ActivityResults
}

Java

Intent intent = new Intent(Intent.ACTION_VIEW);
String referrer = "<Your referrer string>";
String id = "<Package name of the app to be installed>";
String callerId = "<Package name of your third-party app store>";

// Retrieve the app-specific token from your processed catalog export
byte[] catalogToken = getVerificationTokenByDocId(id);

intent.setPackage("com.android.vending");
String deepLinkUrl = "https://play.google.com/d?id=" + id + "&referrer=" + referrer;
intent.setData(Uri.parse(deepLinkUrl));

// Set the required intent extras
intent.putExtra("overlay", true);
intent.putExtra("callerId", callerId);
intent.putExtra("catalog_token", catalogToken);

PackageManager packageManager = context.getPackageManager();
if (intent.resolveActivity(packageManager) != null) {
  startActivityForResult(intent, 0); // Call with a request code to receive ActivityResults
}

Inline Install API 參數

您必須在 Intent 網址中傳遞下列參數，或以 Intent Extras 的形式傳遞，才能授權進行內嵌安裝：

欄位 位置 說明 必填
id 網址查詢 要安裝的目標應用程式套件名稱。 是
referrer 網址查詢 選用的參照網址追蹤字串。 否
overlay 意圖額外資訊 設為 true 即可要求內嵌半頁介面。 是
callerId 意圖額外資訊 已核准的第三方應用程式商店套件名稱。 是
catalog_token 意圖額外資訊 目錄存取權匯出資料中提供的專屬傳送權杖。注意：系統會驗證權杖是否為最新版本、目標套件是否相符，以及呼叫端套件是否相符。 是

(選用) Google Play 內嵌安裝，並顯示安裝狀態疊加層

如要透過內嵌安裝流程顯示安裝狀態疊加層，您必須使用 Google Play HSDP SDK，將 Google Play 內嵌安裝功能與「持續性功能提示」整合。

如要顯示內嵌安裝流程和持續性功能提示：

  • 目標裝置的 Google Play 商店版本必須為 52.5 以上。
  • Android API 級別必須為 24 (Android M) 以上。
  • 整合 HSDP SDK 2.0.2 版 (即將推出) 以上版本。

整合範例

// Step 1: Initialize HSDP Service
// Note: Calling create(activity) automatically configures useServiceBasedHsdp = false
// (Activity Path) under the hood without requiring manual boolean flags.
val hsdpService = HsdpDeepLinkServiceFactory.create(activity)

// Step 2: Construct Extra Query Parameters with Catalog Token
val extraQueryParams = mapOf("catalog_token" to "YOUR_SECURE_CATALOG_TOKEN_VALUE")

// Step 3: Trigger Inline Install Flow
hsdpService.open(
    targetAppPackageName = "com.example.targetapp",
    referrer = "3pas_ad_campaign_123",
    listener = object : HsdpDeepLinkServiceListener {
        override fun onDeepLinkStarted() {
            // Inline details dialog started successfully
        }
        override fun onAffordanceStarted() {
            // HPOA persistent affordance UI attached
        }
        override fun onAffordanceEnded() {
            // Affordance UI detached
        }
        override fun onError(errorMessage: String) {
            // Handle error or fallback
        }
    },
    extraQueryParams = extraQueryParams
)

停止追蹤可供性範例

允許呼叫端應用程式手動停止追蹤安裝狀態，並關閉 HPOA 疊加層。注意：這不會關閉 HSDP 安裝工作表本身，只會關閉提示。

// Stop tracking the installation state and dismiss the affordance overlay
hsdpService.stopAffordance(
    targetAppPackageName = "com.example.targetapp",
    listener = object : HsdpDeepLinkService.AffordanceListener {
        override fun onAffordanceStopped() {
            // Affordance overlay stopped successfully
        }
    }
)

功能提示狀態和使用者體驗

「Google Play 內嵌安裝」功能 (搭配「持續性功能提示」功能) 有兩種視覺狀態：

  1. 安裝狀態：顯示目標應用程式的縮圖和安裝進度微調器。點選縮圖會重新啟動 HSDP 安裝表單。
  2. 安裝後狀態：顯示目標應用程式圖示和「開啟」動作。點選縮圖即可開啟新安裝的應用程式。
安裝中 安裝後
安裝狀態 (展開)

安裝狀態 (已收合)		 安裝後狀態