Installazioni in linea di Google Play (store di app di terze parti)

Questa pagina descrive come gli store di app di terze parti registrati al programma di accesso al catalogo possono integrare le installazioni integrate di Google Play, una funzionalità che consente agli store di app per Android di terze parti negli Stati Uniti di indirizzare gli utenti al download delle app di Play tramite Google Play alle stesse condizioni di qualsiasi altro download effettuato direttamente tramite il Google Play Store.

Prerequisiti

Prima di integrare l'API per l'installazione integrata nel tuo store di app di terze parti, devi completare la seguente configurazione in Google Play Console:

1. Registrati al programma di accesso al catalogo di Play:segui le istruzioni per la registrazione.
2. Attiva l'accesso al catalogo:registrati al programma di accesso al catalogo tramite le impostazioni di Play Console.
3. Recupera i token di consegna:elabora l'esportazione del catalogo delle app di Play che ti è stata fornita. Questa esportazione contiene il catalog_token (token di consegna) necessario per ogni app che hai l'autorizzazione a distribuire.

Requisiti

Affinché l'interfaccia a metà schermata venga visualizzata correttamente dagli utenti, devono essere soddisfatti i seguenti requisiti:

• L'utente deve trovarsi negli Stati Uniti.
• La versione minima di Google Play sul dispositivo deve essere la 52.3.
• Il livello API Android deve essere 24 o superiore.
• Devi fornire un catalog_token valido e non scaduto per accedere al Play Store.

Richiama le installazioni integrate dal tuo store di app

Per richiamare la metà schermata di installazione integrata, crea un'istanza della Intent classe che abbia come target l'URL del link diretto di Google Play e includa il tuo catalog_token univoco.

Utilizza il seguente codice campione (Kotlin o Java) come linea guida:

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
}

Parametri dell'API per l'installazione integrata

I seguenti parametri devono essere passati nell'URL dell'intent o come extra dell'intent per autorizzare l'installazione integrata:

(Facoltativo) Installazione integrata di Google Play con overlay dello stato di installazione

Per mostrare un overlay dello stato di installazione con il flusso di installazione integrata, devi integrare la funzionalità di installazione integrata di Google Play con l'elemento persistente utilizzando l'SDK HSDP di Google Play.

Affinché venga visualizzato il flusso di installazione integrata con l'elemento persistente:

• La versione minima del Google Play Store del dispositivo di destinazione deve essere la 52.5 o versioni successive.
• Il livello API Android deve essere 24 (Android M) o versioni successive.
• Esegui l'integrazione con l'SDK HSDP con la versione 2.0.2 (disponibile a breve) o versioni successive.

Esempio di integrazione

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

Esempio di interruzione del monitoraggio dell'elemento

Consente all'app chiamante di interrompere manualmente il monitoraggio dello stato di installazione e chiudere l'overlay HPOA. Nota: in questo modo non verrà chiusa la scheda di installazione HSDP, ma solo l'elemento.

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

Stati dell'elemento e UX

La funzionalità di installazione integrata di Google Play con l'elemento persistente ha due stati visivi:

1. Stato di installazione: mostra una miniatura dell'app di destinazione e un indicatore di avanzamento dell'installazione. Se fai clic sulla miniatura, viene riavviata la scheda di installazione HSDP.
2. Stato post-installazione: mostra l'icona dell'app di destinazione con un'azione "Apri". Se fai clic sulla miniatura, viene aperta l'app appena installata.

Installazione	Post-installazione