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 以上。
  • 您必須提供有效且未過期的catalog_token，才能存取 Play 商店。

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

如要叫用內嵌安裝半頁式畫面，請建立 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
String 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
}

內嵌安裝 API 參數

您必須在意圖網址中或以意圖額外項目的形式傳遞下列參數，才能授權內嵌安裝：

欄位 類型 位置 說明 必填
id String 網址查詢 要安裝的目標應用程式套件名稱。 是
referrer String 網址查詢 選用的參照網址追蹤字串。 否
overlay boolean Intent Extra 設為 true，即可要求內嵌半頁式介面。 是
callerId String Intent Extra 已核准第三方應用程式商店的套件名稱。 是
catalog_token String Intent Extra 目錄存取權匯出資料中提供的專屬提交權杖。注意：系統會驗證權杖的新鮮度、目標套件比對和呼叫端套件比對。 是

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

如要在內嵌安裝流程中顯示安裝狀態疊加層，您必須使用 Google Play HSDP SDK，將 Google Play 內嵌安裝與永久功能整合。

如要顯示內嵌安裝流程和持續性功能，請按照下列步驟操作：

  • 目標裝置的 Google Play 商店版本必須為 52.6 以上。
  • Android API 級別必須為 24 (Android M) 以上。
  • 整合 HSDP SDK 2.1.0 以上版本。

整合範例

Kotlin

// 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
)

Java

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

// Step 2: Construct Extra Query Parameters with Catalog Token
Map<String, String> extraQueryParams = new HashMap<>();
extraQueryParams.put("catalog_token", "YOUR_SECURE_CATALOG_TOKEN_VALUE");

// Step 3: Trigger Inline Install Flow
hsdpService.open(
    "com.example.targetapp",
    "3pas_ad_campaign_123",
    new HsdpDeepLinkServiceListener() {
      @Override
      public void onDeepLinkStarted() {
        // Inline details dialog started successfully
      }

      @Override
      public void onAffordanceStarted() {
        // HPOA persistent affordance UI attached
      }

      @Override
      public void onAffordanceEnded() {
        // Affordance UI detached
      }

      @Override
      public void onError(String errorMessage) {
        // Handle error or fallback
      }
    },
    extraQueryParams);

停止追蹤示能範例

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

Kotlin

// 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
        }
    }
)

Java

// Stop tracking the installation state and dismiss the affordance overlay
hsdpService.stopAffordance(
    "com.example.targetapp",
    new HsdpDeepLinkService.AffordanceListener() {
      @Override
      public void onAffordanceStopped() {
        // Affordance overlay stopped successfully
      }
    });

示能狀態和使用者體驗

Google Play 內嵌安裝與持續性功能有兩種視覺狀態：

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

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