本頁面由 Cloud Translation API 翻譯而成。

Google Play 內嵌安裝（SDK）

本頁介紹了第三方 SDK 如何整合 inline install，這是 Google Play 的新測試功能，它以半頁介面的形式呈現 Google Play 應用程式產品詳情。線上安裝使用戶能夠在不離開應用程式上下文的情況下體驗無縫的應用程式安裝流程。

第三方 SDK 開發者可以將內嵌安裝功能整合到他們的 SDK 中，使使用這些 SDK 的應用程式開發者能夠存取其應用程式的內嵌安裝功能。

需求條件

若要在應用程式中顯示內嵌安裝半頁介面：

Google Play 的最低版本必須為 40.4。
Android API 等級必須為 23 或更高。

流程架構

下圖展示了內嵌安裝過程的架構：

Google Play 伺服器產生具有關聯資料的驗證加密 (AEAD) 加密金鑰，並將這些金鑰匯入 Google Cloud Platform (GCP) Secret Manager 實例。
第三方整合商從 GCP Secret Manager 中檢索 AEAD 金鑰。
第三方整合商對線上安裝進行加密Intent數據，產生用於調用內聯安裝意圖的深度連結中傳遞的密文，並將深度連結以回應的形式發送給客戶端。
當使用者點擊深度連結時，Google Play 應用程式會處理該意圖。

若要設定第三方 SDK 以使用內嵌安裝流程，請完成下列步驟。

在 Google Cloud Project 中建立服務帳號

在這個步驟中，您將使用 Google Cloud 控制台設定服務帳戶。

設定 Google Cloud 專案：
- 建立 Google Cloud 組織。建立 Google Workspace 或 Cloud Identity 帳戶並將其與網域名稱關聯時，組織資源會自動建立。有關詳細信息，請參閱建立和管理組織資源。
- 使用上一個步驟建立的 Google Cloud 帳戶登入 GCP 控制台，然後建立一個 Google Cloud 專案。有關詳細信息，請參閱建立 Google Cloud 專案。
在建立的 Google Cloud 專案中建立服務帳號。此服務帳號用作 Google Cloud Identity，代表您的伺服器存取對稱金鑰。有關詳細信息，請參閱建立服務帳戶。
使用在意願表單中輸入的 Google Workspace 客戶 ID (GWCID) / Dasher ID。
建立並下載該服務帳戶的私密金鑰。
為該服務帳戶建立金鑰。有關詳細信息，請參閱建立服務帳戶金鑰。
下載服務帳戶金鑰並將其保存在您的伺服器上，因為它用於對存取 Google Cloud 資源的對稱金鑰進行驗證。有關詳細信息，請參閱以取得服務帳戶金鑰。

檢索憑證

在此步驟中，您將從 Secret Manager 中檢索對稱金鑰，並將其安全地儲存在您自己的伺服器儲存中（例如，儲存在 JSON 檔案中）。此金鑰用於產生內聯安裝資料密文。

secret_id/secretId 值指的是 Secret Manager 內部的金鑰名稱；該名稱是透過在 Play 提供的值 sdk_id 前面加上 hsdp-3p-key- 產生的。例如，如果 sdk_id 是 abc，則金鑰名稱為 hsdp-3p-key-abc。

秘密版本每週二下午 2 點（UTC）更新。第二新的鑰匙可以繼續使用到下一次輪換，鑰匙材料應該每週新鮮獲取並儲存。

Python 範例

下列程式碼範例會使用儲存在 JSON 檔案中的存取權權杖，存取 GCP Secret Manager 中的金鑰素材，並將其列印到控制台。

#!/usr/bin/env python3
# Import the Secret Manager client library.
from google.cloud import secretmanager
from google.oauth2 import service_account
import google_crc32c

# Create a service account key file.
service_account_key_file = "<json key file of the service account>"
credentials = service_account.Credentials.from_service_account_file(service_account_key_file)

# Create the Secret Manager client.
client = secretmanager.SecretManagerServiceClient(
  credentials=credentials
)

# Build the resource name of the secret version.
name = f"projects/prod-play-hsdp-3p-caller-auth/secrets/<secret_id>/versions/latest"

# Access the secret version.
response = client.access_secret_version(request={"name": name})

# Verify payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(response.payload.data)
if response.payload.data_crc32c != int(crc32c.hexdigest(), 16):
    print("Data corruption detected.")

# A keyset created with "tinkey create-keyset --key-template=AES256_GCM". Note
# that this keyset has the secret key information in cleartext.
keyset = response.payload.data.decode("UTF-8")

# WARNING: Do not print the secret in a production environment. Please store it
# in a secure storage.
with open('<key file name>', 'w') as f:
    f.write(keyset)

Java 範例

以下程式碼範例使用儲存在 JSON 檔案中的存取權令牌來存取 GCP Secret Manager 中的金鑰材料，並將其寫入 JSON 檔案。

import static java.nio.charset.StandardCharsets.UTF_8;
import com.google.api.gax.core.CredentialsProvider;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.ServiceAccountCredentials;
import com.google.cloud.secretmanager.v1.AccessSecretVersionResponse;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
import com.google.cloud.secretmanager.v1.SecretVersionName;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.PrintWriter;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.zip.CRC32C;
import java.util.zip.Checksum;

/** */
final class ThirdPartySecretAccessGuide {

  private ThirdPartySecretAccessGuide() {}

  public static void main(String[] args) throws IOException {
    accessSecretVersion();
  }

  public static void accessSecretVersion() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "projectId";
    String secretId = "secretId";
    String versionId = "versionId";
    String accessTokenPrivateKeyPath = "path/to/credentials.json";
    String secretMaterialOutputPath = "path/to/secret.json";
    accessSecretVersion(
        projectId, secretId, versionId, accessTokenPrivateKeyPath, secretMaterialOutputPath);
  }

  // Access the payload for the given secret version if one exists. The version
  // can be a version number as a string (e.g. "5") or an alias (e.g. "latest").
  public static void accessSecretVersion(
      String projectId,
      String secretId,
      String versionId,
      String accessTokenPrivateKeyPath,
      String secretMaterialOutputPath)
      throws IOException {

    // We can explicitly instantiate the SecretManagerServiceClient (below) from a json file if we:
    // 1. Create a CredentialsProvider from a FileInputStream of the JSON file,
    CredentialsProvider credentialsProvider =
        FixedCredentialsProvider.create(
            ServiceAccountCredentials.fromStream(new FileInputStream(accessTokenPrivateKeyPath)));

    // 2. Build a SecretManagerService Settings object from that credentials provider, and
    SecretManagerServiceSettings secretManagerServiceSettings =
        SecretManagerServiceSettings.newBuilder()
            .setCredentialsProvider(credentialsProvider)
            .build();

    // 3. Initialize client that will be used to send requests by passing the settings object to
    // create(). This client only needs to be created once, and can be reused for multiple requests.
    // After completing all of your requests, call the "close" method on the client to safely clean
    // up any remaining background resources.
    try (SecretManagerServiceClient client =
        SecretManagerServiceClient.create(secretManagerServiceSettings)) {
      SecretVersionName secretVersionName = SecretVersionName.of(projectId, secretId, versionId);

      // Access the secret version.
      AccessSecretVersionResponse response = client.accessSecretVersion(secretVersionName);

      // Verify checksum. The used library is available in Java 9+.
      // If using Java 8, you may use the following:
      // https://github.com/google/guava/blob/e62d6a0456420d295089a9c319b7593a3eae4a83/guava/src/com/google/common/hash/Hashing.java#L395
      byte[] data = response.getPayload().getData().toByteArray();
      Checksum checksum = new CRC32C();
      checksum.update(data, 0, data.length);
      if (response.getPayload().getDataCrc32C() != checksum.getValue()) {
        System.out.printf("Data corruption detected.");
        return;
      }

      String payload = response.getPayload().getData().toStringUtf8();
      // Print the secret payload.
      //
      // WARNING: Do not print the secret in a production environment - this
      // snippet is showing how to access the secret material.
      System.out.printf("Plaintext: %s\n", payload);

      // Write the JSON secret material payload to a json file
      try (PrintWriter out =
          new PrintWriter(Files.newBufferedWriter(Paths.get(secretMaterialOutputPath), UTF_8))) {
        out.write(payload);
      } catch (Exception e) {
        e.printStackTrace();
      }
    }
  }
}

設定應用程式預設憑證

如果您不想在 Java 實作中使用 CredentialsProvider 將私鑰傳遞給 JSON 文件，您可以透過設定應用程式預設憑證 (ADC) 來修改實作：

告訴客戶端庫服務帳戶金鑰在哪裡可以找到。
將 Maven 依附元件新增至 Java 專案。
呼叫SecretManagerServiceClient.create()，它會自動取得驗證（因為步驟 1）。

這些步驟透過以下方式修改 Java 實作：

無需建立 CredentialsProvider 和 SecretManagerServiceSettings 物件。
將呼叫改為 SecretManagerServiceClient.create()，使其不包含任何參數。

創建密文並生成深度鏈接

在此步驟中，您將使用 Tink 加密庫從 InlineInstallData protobuf 物件建立 enifd (InlineInstallData 密文)。 InlineInstallData 原型定義如下：

syntax = "proto2";
package hsdpexperiments;
option java_package = "com.google.hsdpexperiments";
option java_multiple_files = true;

// InlineInstallData is used by 3p auth callers to generate "encrypted inline
// flow data" (enifd) which is decrypted in PGS to verify authenticity and
// freshness.
message InlineInstallData {
  // The timestamp which indicates the time encrypted data is generated.
  // Used to validate freshness (i.e. generation time in past 4 hours).
  // Required.
  optional int64 timestamp_ms = 1;

  // The docid of the app that we want to open inline install page for.
  // This is the package name.
  // Required.
  optional string target_package_name = 2;

  // This is the name of the app requesting the ad from Google Ad Serving
  // system.
  // Required.
  optional string caller_package_name = 3;

  // This is the advertising id that will be collected by 3P Ad SDKs.
  // Optional.
  optional string advertising_id = 4;

  // This is used to indicate the network from where the inline install was
  // requested.
  // Required.
  optional string ad_network_id = 5;
}

在此步驟中，您還需要使用以下參數建立深度連結 URL：

欄位	說明	必填
id	要安裝的應用的軟體包名稱。	是
內嵌	如果請求內嵌安裝半頁，則設定為 `true`；如果設定為 `false`，則意圖會深度連結到 Google Play。	是
恩尼夫德	3P SDK 的加密標識符。	是
lft	內部識別符。	是
3pAuthCallerId	SDK 標識符。	是
商店資訊	一個可選參數，用於指定自訂商店清單的目標。	否
推薦人	可選的 referrer 追蹤字串。	否

Python 範例

以下命令從 InlineInstallData.proto 產生 Python 程式碼：

protoc InlineInstallData.proto --python_out=.

以下 Python 範例程式碼建構 InlineInstallData 並使用對稱金鑰對其進行加密，以建立密文：

#!/usr/bin/env python3

# Import the Secret Manager client library.
import base64
import time
import inline_install_data_pb2 as InlineInstallData
import tink
from tink import aead
from tink import cleartext_keyset_handle

# Read the stored symmetric key.
with open("example3psecret.json", "r") as f:
  keyset = f.read()

"""Encrypt and decrypt using AEAD."""
# Register the AEAD key managers. This is needed to create an Aead primitive later.
aead.register()

# Create a keyset handle from the cleartext keyset in the previous
# step. The keyset handle provides abstract access to the underlying keyset to
# limit access of the raw key material. WARNING: In practice, it is unlikely
# you will want to use a cleartext_keyset_handle, as it implies that your key
# material is passed in cleartext, which is a security risk.
keyset_handle = cleartext_keyset_handle.read(tink.JsonKeysetReader(keyset))

# Retrieve the Aead primitive we want to use from the keyset handle.
primitive = keyset_handle.primitive(aead.Aead)

inlineInstallData = InlineInstallData.InlineInstallData()
inlineInstallData.timestamp_ms = int(time.time() * 1000)
inlineInstallData.target_package_name = "x.y.z"
inlineInstallData.caller_package_name = "a.b.c"
inlineInstallData.ad_network_id = "<sdk_id>"

# Use the primitive to encrypt a message. In this case the primary key of the
# keyset will be used (which is also the only key in this example).
ciphertext = primitive.encrypt(inlineInstallData.SerializeToString(), b'<sdk_id>')
print(f"InlineInstallData Ciphertext: {ciphertext}")

# Base64 Encoded InlineInstallData Ciphertext
enifd = base64.urlsafe_b64encode(ciphertext).decode('utf-8')
print(enifd)

# Deeplink
print(f"https://play.google.com/d?id={inlineInstallData.target_package_name}\&inline=true\&enifd={enifd}\&lft=1\&3pAuthCallerId={inlineInstallData.ad_network_id}")

執行下列指令，執行 Python 指令碼：

python <file_name>.py

Java 範例

以下命令從 InlineInstallData.proto 產生 Java 程式碼：

protoc InlineInstallData.proto --java_out=.

以下 Java 範例程式碼建構 InlineInstallData 並使用對稱金鑰對其進行加密，以建立密文：

package com.google.hsdpexperiments;

import static com.google.common.io.BaseEncoding.base64Url;
import static java.nio.charset.StandardCharsets.UTF_8;

import com.google.common.flags.Flag;
import com.google.common.flags.FlagSpec;
import com.google.common.flags.Flags;
import com.google.crypto.tink.Aead;
import com.google.crypto.tink.InsecureSecretKeyAccess;
import com.google.crypto.tink.KeysetHandle;
import com.google.crypto.tink.TinkJsonProtoKeysetFormat;
import com.google.crypto.tink.aead.AeadConfig;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.security.Security;
import java.time.Duration;
import org.conscrypt.Conscrypt;

/** info on encryption in https://github.com/google/tink#learn-more */
final class ThirdPartyEnifdGuide {

  @FlagSpec(
      name = "third_party_id",
      help = "the identifier associated with the 3p for which to generate the enifd")
  private static final Flag<String> thirdPartyAuthCallerId = Flag.value("");

  @FlagSpec(name = "package_name", help = "the package name of the target app")
  private static final Flag<String> packageName = Flag.value("");


  @FlagSpec(name = "caller_package_name", help = "the package name of the caller app")
  private static final Flag<String> callerPackageName = Flag.value("");

  @FlagSpec(name = "secret_filename", help = "the path to the json file with the secret material")
  private static final Flag<String> secretFilename = Flag.value("");

  private ThirdPartyEnifdGuide() {}

  public static void main(String[] args) throws Exception {
    // parse flags
    Flags.parse(args);

    // File keyFile = new File(args[0]);
    Path keyFile = Paths.get(secretFilename.get());

    // Create structured inline flow data
    InlineInstallData idrp =
        InlineInstallData.newBuilder()
            .setTargetPackageName(packageName.get())
            .setCallerPackageName(callerPackageName.get())
            .setTimestampMs(System.currentTimeMillis())
            .setAdNetworkId(thirdPartyAuthCallerId.get())
            .build();

    // we can print this out here to make sure it's well formatted, this will help debug
    System.out.println(idrp.toString());

    // Register all AEAD key types with the Tink runtime.
    Conscrypt.checkAvailability();
    Security.addProvider(Conscrypt.newProvider());
    AeadConfig.register();

    // Read AEAD key downloaded from secretmanager into keysethandle
    KeysetHandle handle =
        TinkJsonProtoKeysetFormat.parseKeyset(
            new String(Files.readAllBytes(keyFile), UTF_8), InsecureSecretKeyAccess.get());

    // Generate enifd using tink library
    Aead aead = handle.getPrimitive(Aead.class);
    byte[] plaintext = idrp.toByteArray();
    byte[] ciphertext = aead.encrypt(plaintext, thirdPartyAuthCallerId.get().getBytes(UTF_8));
    String enifd = base64Url().omitPadding().encode(ciphertext);

    // Build deeplink, escaping ampersands (TODO: verify this is necessary while testing e2e)
    String deeplink =
        "https://play.google.com/d?id="
            + packageName.get()
            + "\\&inline=true\\&enifd="
            + enifd
            + "\\&lft=1\\&3pAuthCallerId="
            + thirdPartyAuthCallerId.get();

    System.out.println(deeplink);
  }
}

最後，將 Java 程式編譯成二進位文件，並使用以下程式碼呼叫它：

path/to/binary/ThirdPartyEnifdGuide --secret_filename=path/to/jsonfile/example3psecret.json --package_name=<package_name_of_target_app> --third_party_id=<3p_caller_auth_id>

secret_filename 標誌指定包含秘密資料的 JSON 檔案的路徑。
package_name 標誌是目標應用程式的文件 ID。
third_party_id 旗標用於指定第三方呼叫端授權 ID (即 <sdk_id>)。

啟動內嵌安裝意圖

若要測試上一步驟產生的深度鏈接，請將 Android 裝置（確保已啟用 USB 偵錯）連接到已安裝 ADB 的工作站，然後執行以下命令：

adb shell am start "<output_from_the_previous_python_or_java_code>"

在客戶端程式碼中，使用下列方法之一（Kotlin 或 Java）發送意圖。

Kotlin

val intent = Intent(Intent.ACTION_VIEW)
val deepLinkUrl = "<output_from_the_previous_python_or_java_code>"
intent.setPackage("com.android.vending")
intent.data = Uri.parse(deepLinkUrl)
val packageManager = context.getPackageManager()
if (intent.resolveActivity(packageManager) != null) {
  startActivityForResult(intent, 0)
} else {
  // Fallback to deep linking to full Play Store.
}

Java

Intent intent = new Intent(Intent.ACTION_VIEW);
String id = "exampleAppToBeInstalledId";
String deepLinkUrl = "<output_from_the_previous_python_or_java_code>";
intent.setPackage("com.android.vending");
intent.setData(Uri.parse(deepLinkUrl));
PackageManager packageManager = context.getPackageManager();
if (intent.resolveActivity(packageManager) != null) {
  startActivityForResult(intent, 0);
} else {
  // Fallback to deep linking to full Play Store.
}

附錄

以下各節針對某些使用情境提供更多指導。

準備 Python 環境

若要執行 Python 範例程式碼，請在工作站上設定 Python 環境並安裝所需的依賴項。

設定 Python 環境：
1. 安裝 python3.11（如果已安裝，請跳過此步驟）：
```
sudo apt install python3.11
```
2. 安裝 pip：
```
sudo apt-get install pip
```
3. 安裝 virtualenv:
```
sudo apt install python3-virtualenv
```
4. 建立虛擬環境（Tink 依賴項必需）：
```
virtualenv inlineinstall --python=/usr/bin/python3.11
```
進入虛擬環境：
```
source inlineinstall/bin/activate
```
更新 pip：
```
python -m pip install --upgrade pip
```

安裝所需依賴項：

安裝 Tink：
```
pip install tink
```
安裝 Google crc32c：
```
pip install google-crc32c
```

安裝 Secret Manager：

pip install google-cloud-secret-manager

安裝 protobuf 編譯器：
```
sudo apt install protobuf-compiler
```

C++ 編碼生成

以下是一個我們編寫並經過內部驗證的 C++ 範例，用於產生 enifd。

可以使用以下 C++ 程式碼產生 enifd：

// A command-line example for using Tink AEAD w/ key template aes128gcmsiv to
// encrypt an InlineInstallData proto.
#include <chrono>
#include <iostream>
#include <memory>
#include <string>

#include "<path_to_protoc_output>/inline_install_data.proto.h"
#include "absl/flags/flag.h"
#include "absl/flags/parse.h"
#include "absl/strings/escaping.h"
#include "absl/strings/string_view.h"
#include "tink/cc/aead.h"
#include "tink/cc/aead_config.h"
#include "tink/cc/aead_key_templates.h"
#include "tink/cc/config/global_registry.h"
#include "tink/cc/examples/util/util.h"
#include "tink/cc/keyset_handle.h"
#include "tink/cc/util/status.h"
#include "tink/cc/util/statusor.h"

ABSL_FLAG(std::string, keyset_filename, "",
          "Keyset file (downloaded from secretmanager) in JSON format");
ABSL_FLAG(std::string, associated_data, "",
          "Associated data for AEAD (default: empty");

namespace {

using ::crypto::tink::Aead;
using ::crypto::tink::AeadConfig;
using ::crypto::tink::KeysetHandle;
using ::crypto::tink::util::Status;
using ::crypto::tink::util::StatusOr;

}  // namespace

namespace tink_cc_examples {

// AEAD example CLI implementation.
void AeadCli(const std::string& keyset_filename,
             absl::string_view associated_data) {
  Status result = AeadConfig::Register();
  if (!result.ok()) {
    std::clog << "Failed to register AeadConfig";
    return;
  }

  // Read the keyset from file.
  StatusOr<std::unique_ptr<KeysetHandle>> keyset_handle =
      ReadJsonCleartextKeyset(keyset_filename);
  if (!keyset_handle.ok()) {
    std::clog << "Failed to read json keyset";
    return;
  }

  // Get the primitive.
  StatusOr<std::unique_ptr<Aead>> aead =
      (*keyset_handle)
          ->GetPrimitive<crypto::tink::Aead>(
              crypto::tink::ConfigGlobalRegistry());
  if (!aead.ok()) {
    std::clog << "Failed to get primitive";
    return;
  }

  // Instantiate the enifd.
  hsdpexperiments::InlineInstallData iid;

  iid.set_timestamp_ms(std::chrono::duration_cast<std::chrono::milliseconds>(
                           std::chrono::system_clock::now().time_since_epoch())
                           .count());
  iid.set_target_package_name("<TARGET_PACKAGE_NAME>");
  iid.set_caller_package_name("<CALLER_PACKAGE_NAME>");
  iid.set_ad_network_id("<SDK_ID>");

  // Compute the output.
  StatusOr<std::string> encrypt_result =
      (*aead)->Encrypt(iid.SerializeAsString(), associated_data);
  if (!encrypt_result.ok()) {
    std::clog << "Failed to encrypt Inline Install Data";
    return;
  }
  const std::string& output = encrypt_result.value();

  std::string enifd;
  absl::WebSafeBase64Escape(output, &enifd);

  std::clog << "enifd: " << enifd << '\n';
}

}  // namespace tink_cc_examples

int main(int argc, char** argv) {
  absl::ParseCommandLine(argc, argv);

  std::string keyset_filename = absl::GetFlag(FLAGS_keyset_filename);
  std::string associated_data = absl::GetFlag(FLAGS_associated_data);

  std::clog << "Using keyset from file " << keyset_filename
            << " to AEAD-encrypt inline install data with associated data '"
            << associated_data << "'." << '\n';

  tink_cc_examples::AeadCli(keyset_filename, associated_data);
  return 0;
}

此程式碼改編自 Tink 文件中的 sample。

Google Play 內嵌安裝（SDK） 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

需求條件

流程架構

在 Google Cloud Project 中建立服務帳號

檢索憑證

Python 範例

Java 範例

設定應用程式預設憑證

創建密文並生成深度鏈接

Python 範例

Java 範例

啟動內嵌安裝意圖

Kotlin

Java

附錄

準備 Python 環境

C++ 編碼生成

Google Play 內嵌安裝（SDK）