Google Play 内嵌安装（第三方应用商店）

本页面介绍了已加入目录访问权限计划的第三方应用商店如何集成 Google Play 内嵌安装功能。借助该功能，美国第三方 Android 应用商店可引导用户通过 Google Play 下载 Google Play 中的应用，其下载条款与直接在 Google Play 商店下载完全一致。

前提条件

在第三方应用商店中集成内嵌式安装 API 之前，您必须在 Google Play 管理中心内完成以下设置：

  1. 加入 Google Play 目录访问权限计划：按照注册说明操作。
  2. 选择加入目录访问权限计划：通过 Play 管理中心设置加入目录访问权限计划。
  3. 检索分发令牌：处理提供给您的 Google 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 参数

您必须在 intent 网址中或作为 intent extra 传递以下参数，才能授权内嵌安装：

字段 类型 位置 说明 必填
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. 安装后状态：显示目标应用图标和“打开”操作。点击缩略图会打开新安装的应用。
正在安装 安装后
安装状态（展开）

安装状态（收起）		 安装后状态