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

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

前提条件

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

  1. 加入 Google Play 目录访问权限计划： 按照 加入说明操作。
  2. 选择加入目录访问权限计划： 通过 Play 管理中心设置加入目录访问权限计划。
  3. 检索传送令牌： 处理向您提供的 Play 应用目录导出内容。此导出内容包含您有资格分发的每个应用所需的 catalog_token（传送令牌）。

要求

如需让半屏界面成功向用户显示，必须满足以下要求：

  • 用户必须位于美国 。
  • 设备上的最低 Google Play 版本必须为 52.3 。
  • Android API 级别必须为 24 或更高版本 。
  • 您必须提供有效且未过期的 catalog_token，才能访问 Play 商店。

从应用商店调用内嵌式安装

如需调用内嵌式安装半屏界面，请创建以 Google Play 深层链接网址为目标的 Intent类的实例，并添加您的唯一 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
}

内嵌式安装 API 参数

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

字段 位置 说明 必填
id 网址查询 要安装的目标应用的软件包名称。 是
referrer 网址查询 可选的引荐来源网址跟踪字符串。 否
overlay Intent Extra 设置为 true 可请求内嵌式半屏界面。 是
callerId Intent Extra 您获批的第三方应用商店的软件包名称。 是
catalog_token Intent Extra 在目录访问权限导出内容中提供的唯一传送令牌。注意： 系统会验证令牌的新鲜度、目标软件包匹配情况和调用方软件包匹配情况。 是

（可选）Google Play 内嵌式安装（带安装状态叠加层）

如需在内嵌式安装流程中显示安装状态叠加层，您需要使用 Google Play HSDP SDK 将 Google Play 内嵌式安装与 Persistent Affordance 功能集成。

如需显示带 Persistent Affordance 的内嵌式安装流程，请执行以下操作：

  • 目标设备的最低 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
)

停止 Affordance 跟踪示例

允许调用方应用手动停止跟踪安装状态并关闭 HPOA 叠加层。注意：这不会关闭 HSDP 安装表单本身，只会关闭 Affordance。

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

Affordance 状态和用户体验

Google Play 内嵌式安装（带 Persistent Affordance 功能）具有两种视觉状态：

  1. 正在安装状态：显示目标应用的缩略图和安装进度微调框。点击缩略图会重新启动 HSDP 安装表单。
  2. 安装后状态：显示目标应用图标，并提供“打开”操作。点击缩略图会打开新安装的应用。
正在安装 安装后
安装状态（展开）

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