Google Play インライン インストール（サードパーティのアプリストア）

このページでは、カタログ アクセス プログラムに登録しているサードパーティ アプリストアが Google Play のインライン インストールを統合する方法について説明します。この機能により、米国のサードパーティ Android アプリストアは、Google Play ストアから直接行われる他のダウンロードと同じ条件で、Google Play を通じてユーザーを Google Play のアプリのダウンロードに誘導できます。

前提条件

サードパーティのアプリストアにインライン インストール API を統合する前に、Google Play Console で次の設定を完了する必要があります。

1. Google Play カタログ アクセス プログラムに登録する: 登録手順に沿って登録します。
2. カタログ アクセスにオプトインする: Google Play Console の設定でカタログ アクセス プログラムに登録します。
3. 配信トークンを取得する: 提供された Google Play アプリカタログのエクスポートを処理します。このエクスポートには、配信対象となる各アプリに必要な catalog_token（配信トークン）が含まれています。

要件

ハーフシート インターフェースをユーザーに正常に表示するには、次の要件を満たす必要があります。

• お客様は米国に居住している必要があります。
• デバイスの Google Play の最小バージョンは 52.3 である必要があります。
• Android API レベルは 24 以上である必要があります。
• Google Play ストアにアクセスするには、有効期限内の有効な catalog_token を指定する必要があります。

アプリストアからインライン インストールを呼び出す

インライン インストールのハーフシートを呼び出すには、Google Play のディープリンク URL をターゲットとし、一意の catalog_token を含む Intent クラスのインスタンスを作成します。

次のサンプルコード（Kotlin または Java）をガイドラインとして使用します。

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
}

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 URL または Intent Extras として渡す必要があります。

（省略可）インストール ステータス オーバーレイ付きの Google Play インライン インストール

インライン インストール フローでインストール ステータスのオーバーレイを表示するには、Google Play HSDP SDK を使用して、Google Play インライン インストールと永続的アフォーダンス機能を統合する必要があります。

インライン インストール フローで永続的なアフォーダンスを表示するには:

• ターゲット デバイスの Google Play ストアの最小バージョンは 52.6 以上である必要があります。
• Android API レベルは 24（Android M）以降である必要があります。
• バージョン 2.1.0 以降の HSDP SDK と統合します。

統合の例

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

アフォーダンスの状態と UX

永続的なアフォーダンス機能付きの Google Play インライン インストールには、次の 2 つの視覚的状態があります。

1. インストール中状態: ターゲット アプリのサムネイルとインストール進行状況スピナーが表示されます。サムネイルをクリックすると、HSDP インストール シートが再起動します。
2. インストール後の状態: ターゲット アプリアイコンと [開く] アクションが表示されます。サムネイルをクリックすると、新しくインストールされたアプリが開きます。

インストール中	インストール後