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 Android de terceiros nos EUA direcionem os usuários para o download de 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 loja de apps de terceiros, você precisa concluir a seguinte configuração 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 de acesso ao catálogo nas configurações do Play Console.
3. Recuperar tokens de entrega:processe a exportação do catálogo de apps do Google Play 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 corretamente para os usuários, os seguintes requisitos precisam ser atendidos:

• O usuário precisa estar nos EUA.
• A versão mínima do Google Play no dispositivo precisa ser 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 em linha na sua app store

Para invocar a meia página de instalação inline, crie uma instância da classe Intent que tem como destino o URL de link direto do Google Play e inclui 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 Inline Install

Os seguintes parâmetros 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 da instalação

Para mostrar uma sobreposição de status de instalação com o fluxo de instalação inline, é necessário integrar a instalação inline do Google Play ao recurso de conveniência persistente usando o SDK HSDP do Google Play.

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

• A versão mínima da Google Play Store no dispositivo de destino precisa ser 52.5 ou mais recente.
• O nível da API do Android precisa ser 24 (Android M) ou mais recente.
• Integre com o SDK do HSDP com a versão 2.0.2 (em breve) 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 interrupção do rastreamento de affordance

Permite que o app de chamada pare manualmente de rastrear o estado da instalação e dispense a sobreposição do HPOA. Observação: isso não dispensa a própria planilha de instalação do HSDP, apenas a ação.

// 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 de affordance e UX

A instalação inline do Google Play com o recurso Persistent Affordance tem dois estados visuais:

1. Estado de instalação: mostra uma miniatura do app de destino e um spinner de progresso da instalação. Ao clicar na miniatura, a planilha de instalação do HSDP é aberta novamente.
2. Estado pós-instalação: mostra o ícone do app de destino com uma ação "Abrir". Ao clicar na miniatura, o app recém-instalado será aberto.

Instalando	Pós-instalação