Instalaciones integradas de Google Play (tiendas de aplicaciones de terceros)

En esta página, se describe cómo las tiendas de aplicaciones de terceros inscritas en el programa de Acceso al catálogo pueden integrar las instalaciones integradas de Google Play, una función que permite que las tiendas de apps para Android de terceros de EE.UU. dirijan a los usuarios a la descarga de las aplicaciones de Google Play a través de Google Play en virtud de las mismas condiciones que cualquier otra descarga que se realice directamente a través de la Google Play Store.

Requisitos previos

Antes de integrar la API de instalación integrada en tu tienda de apps de terceros, debes completar la siguiente configuración en Google Play Console:

1. Inscríbete en el Programa de acceso al catálogo de Play: Sigue las instrucciones de inscripción.
2. Habilita el acceso al catálogo: Inscríbete en el programa de acceso al catálogo a través de la configuración de Play Console.
3. Recupera los tokens de entrega: Procesa la exportación del catálogo de aplicaciones de Play que se te proporcionó. Esta exportación contiene el catalog_token (token de entrega) necesario para cada aplicación que cumpla con los requisitos para distribuir.

Requisitos

Para que la interfaz de media hoja aparezca correctamente a los usuarios, se deben cumplir los siguientes requisitos:

• El usuario debe estar ubicado en EE.UU.
• La versión mínima de Google Play en el dispositivo debe ser 52.3.
• El nivel de API de Android debe ser 24 o superior.
• Debes proporcionar un catalog_token válido y que no haya vencido para acceder a Play Store.

Invoca instalaciones integradas desde tu tienda de aplicaciones

Para invocar la media hoja de instalación integrada, crea una instancia de la Intent clase que apunte a la URL de vínculo directo de Google Play y que incluya tu catalog_token único.

Usa el siguiente código de muestra (Kotlin o Java) como guía:

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 de la API de instalación integrada

Los siguientes parámetros deben pasarse en la URL de intent o como extras de intent para autorizar la instalación integrada:

(Opcional) Instalación integrada de Google Play con superposición de estado de instalación

Para mostrar una superposición de estado de instalación con el flujo de instalación integrada, deberás integrar la instalación integrada de Google Play con la función de Persistent Affordance usando el SDK de HSDP de Google Play.

Para que aparezca el flujo de instalación integrada con Persistent Affordance, haz lo siguiente:

• La versión mínima de Google Play Store del dispositivo de destino debe ser 52.5 o superior.
• El nivel de API de Android debe ser 24 (Android M) o superior.
• Realiza la integración con el SDK de HSDP con la versión 2.0.2 (próximamente) o superior.

Ejemplo de integración

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

Ejemplo de detención del seguimiento de affordance

Permite que la app llamadora detenga manualmente el seguimiento del estado de instalación y descarte la superposición de HPOA. Nota: Esto no descartará la hoja de instalación de HSDP en sí, solo la affordance.

// 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 y UX

La instalación integrada de Google Play con la función de Persistent Affordance tiene dos estados visuales:

1. Estado de instalación: Muestra una miniatura de la app de destino y un indicador de progreso de instalación. Si haces clic en la miniatura, se vuelve a iniciar la hoja de instalación de HSDP.
2. Estado posterior a la instalación: Muestra el ícono de la app de destino con una acción "Abrir". Si haces clic en la miniatura, se abre la app recién instalada.

Instalando	Posterior a la instalación