Indicazioni sull'integrazione in-app per il programma di offerte esterne

Questa guida descrive come eseguire l'integrazione con le API per supportare le offerte esterne nelle app e nelle regioni idonee. Per scoprire di più sul programma per offerte esterne, inclusi i requisiti di idoneità e l'ambito geografico, consulta i requisiti del programma.

Configurazione della Libreria Fatturazione Play

Per utilizzare le API per offerte esterne, aggiungi la dipendenza della versione 8.2 o successive di Libreria Fatturazione Play alla tua app per Android. Se devi eseguire la migrazione da una versione precedente, segui le istruzioni nella guida alla migrazione prima di tentare di implementare le offerte esterne.

Collegati a Google Play

I primi passaggi della procedura di integrazione sono gli stessi descritti nella guida all'integrazione della fatturazione, tranne per il fatto che devi chiamare enableBillingProgram per indicare che vuoi utilizzare offerte esterne durante l'inizializzazione di BillingClient:

L'esempio seguente mostra l'inizializzazione di un BillingClient con queste modifiche:

Kotlin

val billingClient = BillingClient.newBuilder(context)
  .enableBillingProgram(BillingProgram.EXTERNAL_OFFER)
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .build();

Dopo aver inizializzato BillingClient, devi stabilire una connessione a Google Play come descritto nella guida all'integrazione.

Verifica disponibilità

Per verificare che le offerte esterne siano disponibili per l'utente corrente, chiama isBillingProgramAvailableAsync.

Questa API restituisce BillingResponseCode.OK se sono disponibili offerte esterne. Per informazioni dettagliate su come la tua app deve rispondere ad altri codici di risposta, consulta la sezione Gestione delle risposte.

Kotlin


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingResult: BillingResult,
      billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers unavailable, etc.
            return
        }

        // External offers are available. Continue with steps in the
        // guide.
      }
  })

Java


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      BillingResult billingResult,
      BillingProgramAvailabilityDetails billingProgramAvailabilityDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers being unavailable, etc.
            return;
        }
        // External offers are available. Continue with steps in the
        // guide.
      }
  });

Prepara un token di transazione esterno

Per segnalare una transazione esterna a Google Play, devi disporre di un token di transazione esterna generato dalla libreria Play Billing. Puoi ottenere questo token chiamando l'API createBillingProgramReportingDetailsAsync. Un nuovo token deve essere generato immediatamente prima di indirizzare l'utente fuori dall'app per ogni offerta esterna. I token non devono essere memorizzati nella cache tra le transazioni.

Kotlin

val params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  object : BillingProgramReportingDetailsListener {
    override fun onCreateBillingProgramReportingDetailsResponse(
      billingResult: BillingResult,
      billingProgramReportingDetails: BillingProgramReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            billingProgramReportingDetails?.externalTransactionToken
        // Persist the transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
    }
})

Java

BillingProgramReportingDetailsParams params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();
        // Persist the transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
      }
});

In alternativa, puoi eseguire query sulla funzione di sospensione createBillingProgramReportingDetailsAsync con le estensioni Kotlin in modo da non dover definire un listener:

  val createBillingProgramReportingDetailsResult =
    withContext(context) {
      billingClient
        .createBillingProgramReportingDetails(params)
    }
  // Process the result

Avviare il flusso di offerte esterne

Per avviare un flusso di offerte esterne, la tua app idonea deve chiamare l'API launchExternalLink() dal thread principale dell'app. Questa API accetta come input un oggetto LaunchExternalLinkParams. Per creare un oggetto LaunchExternalLinkParams, utilizza la classe LaunchExternalLinkParams.Builder. Questa classe contiene i seguenti parametri:

  • linkUri: il link al sito web esterno in cui viene offerto il download di contenuti digitali o app. Per i download di app, questo link deve essere registrato e approvato in Play Console.
  • linkType: il tipo di contenuti offerti all'utente.
  • launchMode: specifica la modalità di avvio del link. Per i download di app, devi impostare questo valore su LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.
  • billingProgram: imposta questo valore su BillingProgram.EXTERNAL_OFFER.

Quando chiami il numero launchExternalLink(), potrebbero essere visualizzate finestre di dialogo con informazioni aggiuntive per l'utente in base alle sue impostazioni. A seconda del parametro launchMode, Google Play avvia l'URI del link in un browser esterno o restituisce il flusso alla tua app per avviare l'URI. Nella maggior parte dei casi, puoi utilizzare la modalità LAUNCH_IN_EXTERNAL_BROWSER_OR_APP in cui Play avvierà l'URI per te. Se vuoi un comportamento più personalizzato, ad esempio avviare l'URI in una webview o aprirlo in un browser specifico, puoi utilizzare la modalità CALLER_WILL_LAUNCH_LINK. Per proteggere la privacy dell'utente, assicurati che nell'URI non vengano trasmesse informazioni che consentono l'identificazione personale (PII).

Kotlin


// An activity reference from which the external offers flow will be launched.
val activity = ...;

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    // You can pass along the external transaction token from
    // BillingProgramReportingDetails as a URL parameter in the URI
    .setLinkUri(yourLinkUri)
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
  LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(billingResult: BillingResult) {
    if (billingResult.responseCode == BillingResponseCode.OK) {
      // Proceed with the rest of the external offer flow. If the user
      // purchases an item, be sure to report the transaction to Google Play.
    } else {
      // Handle failures such as retrying due to network errors.
    }
  }
}

billingClient.launchExternalLink(activity, params, listener)

Java


// An activity reference from which the external offers flow will be launched.
Activity activity = ...;

LaunchExternalLinkParams params = LaunchExternalLinkParams.newBuilder()
  .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
  // You can pass along the external transaction token from  
  // BillingProgramReportingDetails as a URL parameter in the URI
  .setLinkUri(yourLinkUri)
  .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
  .setLaunchMode(
    LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
  .build();

LaunchExternalLinkResponseListener listener =
  new LaunchExternalLinkResponseListener() {
    @Override
    public void onLaunchExternalLinkResponse(BillingResult billingResult) {
      if (billingResult.responseCode == BillingResponseCode.OK) {
        // Proceed with the rest of the external offer flow. If the user
        // purchases an item, be sure to report the transaction to Google
        // Play.
      } else {
        // Handle failures such as retrying due to network errors.
      }
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Se imposti LaunchMode su CALLER_WILL_LAUNCH_LINK, devi indirizzare l'utente al di fuori dell'app solo se onLaunchExternalLinkResponse fornisce BillingResponseCode.OK.

Segnalare le transazioni a Google Play

Devi segnalare tutte le transazioni esterne a Google Play chiamando l'API Google Play Developer dal tuo backend. Quando segnali una transazione, devi fornire un externalTransactionToken ottenuto dall'API createBillingProgramReportingDetailsAsync. Se un utente effettua più acquisti, puoi utilizzare lo stesso externalTransactionToken per segnalare ogni acquisto. Per scoprire come segnalare una transazione, consulta la guida all'integrazione backend.

Gestione delle risposte

Quando si verifica un errore, i metodi isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() e launchExternalLink() potrebbero restituire risposte diverse da BillingResponseCode.OK. Prendi in considerazione la gestione di questi codici di risposta nel seguente modo:

  • ERROR: si è verificato un errore interno. Non procedere con la transazione o l'apertura del sito web esterno. Riprova chiamando launchExternalLink() per visualizzare la finestra di dialogo con le informazioni per l'utente la prossima volta che tenti di indirizzarlo all'esterno dell'app.
  • FEATURE_NOT_SUPPORTED: Le API per offerte esterne non sono supportate dal Play Store sul dispositivo attuale. Non procedere con la transazione o l'apertura del sito web esterno.
  • USER_CANCELED: non procedere con l'apertura del sito web esterno. Chiama launchExternalLink() di nuovo per mostrare la finestra di dialogo delle informazioni all'utente la prossima volta che tenti di indirizzare l'utente all'esterno dell'app.
  • BILLING_UNAVAILABLE: La transazione non è idonea per le offerte esterne e pertanto non deve essere eseguita nell'ambito di questo programma. Ciò è dovuto al fatto che l'utente non si trova in un paese idoneo per questo programma o il tuo account non è stato registrato correttamente al programma. In questo caso, controlla lo stato della registrazione nella Play Console.
  • DEVELOPER_ERROR: si è verificato un errore con la richiesta. Utilizza il messaggio di debug per identificare e correggere l'errore prima di procedere.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: si tratta di errori temporanei che devono essere gestiti con criteri di nuovi tentativi appropriati. Nel caso di SERVICE_DISCONNECTED, ristabilisci una connessione con Google Play prima di riprovare.

Testare le offerte esterne

I tester delle licenze devono essere utilizzati per testare l'integrazione delle offerte esterne. Non riceverai fatture per le transazioni avviate dagli account di test delle licenze. Per ulteriori informazioni sulla configurazione dei tester delle licenze, consulta Testare la fatturazione in-app con le licenze dell'applicazione.

Passaggi successivi

Una volta completata l'integrazione in-app, puoi integrare il backend.