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 in linea 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 di installazione in linea 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à schermo 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 in linea dal tuo store di app

Per richiamare la schermata a metà schermo di installazione in linea, 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:

Kotlin

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
}

Java

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
String 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 di installazione in linea

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

Campo Tipo Località Descrizione Obbligatorio
id String URL query Il nome del pacchetto dell'app di destinazione da installare. Sì
referrer String URL query Una stringa di monitoraggio dei referral facoltativa. No
overlay boolean Extra dell'intent Imposta su true per richiedere l'interfaccia a metà schermo in linea. Sì
callerId String Extra dell'intent Il nome del pacchetto del tuo store di terze parti approvato. Sì
catalog_token String Extra dell'intent Il token di consegna univoco fornito nell'esportazione dell'accesso al catalogo. Nota:i token vengono convalidati per la loro validità, la corrispondenza del pacchetto di destinazione e la corrispondenza del pacchetto del chiamante. Sì

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

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

Affinché il flusso di installazione in linea con l'affordance persistente venga visualizzato:

  • La versione minima di Google Play Store del dispositivo di destinazione deve essere la 52.6 o superiore.
  • Il livello API Android deve essere 24 (Android M) o superiore.
  • Esegui l'integrazione con l'SDK HSDP con la versione 2.1.0 o superiore.

Esempio di integrazione

Kotlin

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

Java

// Step 1: Initialize HSDP Service
// Note: Calling create(activity) automatically configures useServiceBasedHsdp = false
// (Activity Path) under the hood without requiring manual boolean flags.
HsdpDeepLinkService hsdpService = HsdpDeepLinkServiceFactory.create(activity);

// Step 2: Construct Extra Query Parameters with Catalog Token
Map<String, String> extraQueryParams = new HashMap<>();
extraQueryParams.put("catalog_token", "YOUR_SECURE_CATALOG_TOKEN_VALUE");

// Step 3: Trigger Inline Install Flow
hsdpService.open(
    "com.example.targetapp",
    "3pas_ad_campaign_123",
    new HsdpDeepLinkServiceListener() {
      @Override
      public void onDeepLinkStarted() {
        // Inline details dialog started successfully
      }

      @Override
      public void onAffordanceStarted() {
        // HPOA persistent affordance UI attached
      }

      @Override
      public void onAffordanceEnded() {
        // Affordance UI detached
      }

      @Override
      public void onError(String errorMessage) {
        // Handle error or fallback
      }
    },
    extraQueryParams);

Esempio di interruzione del monitoraggio dell'affordance

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

Kotlin

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

Java

// Stop tracking the installation state and dismiss the affordance overlay
hsdpService.stopAffordance(
    "com.example.targetapp",
    new HsdpDeepLinkService.AffordanceListener() {
      @Override
      public void onAffordanceStopped() {
        // Affordance overlay stopped successfully
      }
    });

Stati e UX dell'affordance

La funzionalità di installazione in linea di Google Play con affordance 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 schermata 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
Stato di installazione (espanso)

Stato: installazione in corso (compresso)
Stato post-installazione