Instalações em linha do Google Play (app stores de terceiros)

Esta página descreve como as app stores de terceiros inscritas no programa Acesso ao Catálogo podem integrar as instalações inline do Google Play, um recurso que permite que as app stores de terceiros para Android nos EUA direcionem os usuários para o download dos apps do Google Play nos mesmos termos de qualquer outro download feito diretamente na Google Play Store.

Pré-requisitos

Antes de integrar a API de instalação inline na sua app store de terceiros, conclua a configuração a seguir no Google Play Console:

1. Inscreva-se no Programa de Acesso ao Catálogo do Google Play: Siga as instruções de inscrição.
2. Ative o Acesso ao Catálogo:inscreva-se no programa Acesso ao Catálogo nas configurações do Play Console.
3. Recupere os tokens de entrega:processe a exportação do catálogo de apps do Google Play que foi fornecida a você. Essa exportação contém o catalog_token (token de entrega) necessário para cada app que você pode distribuir.

Requisitos

Para que a interface de meia página apareça aos usuários, os seguintes requisitos precisam ser atendidos:

• O usuário precisa estar localizado nos EUA.
• A versão mínima do Google Play no dispositivo precisa ser a 52.3.
• O nível da API Android precisa ser 24 ou mais recente.
• Você precisa fornecer um catalog_token válido e não expirado para acessar a Google Play Store.

Invocar instalações inline na sua app store

Para invocar a meia página de instalação inline, crie uma instância da classe Intent que tenha como destino o URL de link direto do Google Play e inclua seu catalog_token exclusivo.

Use o exemplo de código a seguir (Kotlin ou Java) como diretriz:

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
}

Parâmetros da API de instalação inline

Os parâmetros a seguir precisam ser transmitidos no URL da intent ou como extras da intent para autorizar a instalação inline:

(Opcional) Instalação inline do Google Play com sobreposição de status de instalação

Para mostrar uma sobreposição de status de instalação com o fluxo de instalação inline, você precisa integrar a instalação inline do Google Play ao recurso de disponibilidade persistente usando o SDK do HSDP do Google Play.

Para que o fluxo de instalação inline com disponibilidade persistente apareça:

• A versão mínima da Google Play Store do dispositivo de destino precisa ser a 52.6 ou mais recente.
• O nível da API Android precisa ser 24 (Android M) ou mais recente.
• Integre com o SDK do HSDP com a versão 2.1.0 ou mais recente.

Exemplo de integração

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

Exemplo de como parar o rastreamento de disponibilidade

Permite que o app de chamada pare manualmente de rastrear o estado da instalação e dispensa a sobreposição do HPOA. Observação: isso não dispensa a página de instalação do HSDP, apenas a disponibilidade.

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

Estados e experiência do usuário de disponibilidade

A instalação inline do Google Play com o recurso de disponibilidade persistente tem dois estados visuais:

1. Estado de instalação: mostra uma miniatura do app de destino e um indicador de progresso da instalação. Clicar na miniatura reinicia a página de instalação do HSDP.
2. Estado pós-instalação: mostra o ícone do app de destino com uma ação "Abrir". Clicar na miniatura abre o app instalado.

Instalando	Pós-instalação