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 エクストラとして渡す必要があります。

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

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

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

• ターゲット デバイスの 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
)

アフォーダンス トラッキングの停止例

呼び出し元アプリは、インストール ステータスのトラッキングを手動で停止し、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. インストール後の状態: ターゲット アプリアイコンと [開く] アクションが表示されます。サムネイルをクリックすると、新しくインストールされたアプリが開きます。

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