Aggiungere funzionalità specifiche dei prodotti premio

Un metodo per sbloccare prodotti e vantaggi in-app per i tuoi utenti è creare prodotti con premio, ovvero elementi che gli utenti ricevono dopo aver guardato un annuncio video. Fornendo prodotti con premi, consenti agli utenti di ottenere premi e vantaggi in-app senza dover effettuare acquisti diretti.

Questo documento spiega come implementare la funzionalità specifica per i prodotti premio. La sezione Diagramma del flusso di lavoro di questa pagina illustra la procedura.

Identificare i prodotti premio della tua app

I prodotti premio hanno un SkuType di INAPP. Per garantire che gli utenti possano guardare più annunci e ricevere più premi, i prodotti devono essere consumati.

Prima di poter offrire un prodotto premio a un utente, devi ottenere il SkuDetails per il prodotto. Per farlo, chiama querySkuDetailsAsync() con SkuType.INAPP come tipo di prodotto.

Dichiarare gli annunci idonei all'età

Per facilitare la conformità agli obblighi legali relativi a bambini e utenti minorenni, tra cui la legge statunitense Children's Online Privacy Protection Act (COPPA) e il Regolamento generale sulla protezione dei dati (GDPR), la tua app deve dichiarare quali annunci devono essere trattati come rivolti ai bambini negli Stati Uniti e quali annunci sono rivolti a utenti di età inferiore a quella del consenso applicabile nel loro paese. Il Centro assistenza AdMob spiega quando devi codificare le richieste di annuncio per il trattamento per siti o servizi destinati ai minori e quando devi codificarle per il trattamento per utenti di età inferiore a quella del consenso digitale, nonché gli effetti di questa operazione.

Quando crei il client di fatturazione della tua app, valuta se le richieste di annunci con premio devono essere trattate come rivolte ai minori o se devono essere indirizzate a utenti di età inferiore all'età del consenso digitale. Se le richieste di annunci devono avere queste limitazioni, chiama i metodi setChildDirected() e setUnderAgeOfConsent(), passando i valori appropriati a ciascun metodo.

Il seguente snippet di codice mostra come dichiarare che gli annunci video devono essere adatti ai bambini o agli utenti di età inferiore a quella del consenso:

Kotlin

val billingClient = BillingClient.newBuilder(context)
        .setListener(this)
        .setChildDirected(ChildDirected.CHILD_DIRECTED)
        .setUnderAgeOfConsent(UnderAgeOfConsent.UNDER_AGE_OF_CONSENT)
        .build()

Java

BillingClient billingClient =
    BillingClient.newBuilder(context)
        .setListener(this)
        .setChildDirected(ChildDirected.CHILD_DIRECTED)
        .setUnderAgeOfConsent(UnderAgeOfConsent.UNDER_AGE_OF_CONSENT)
        .build();

Caricare gli annunci video

Prima di mostrare all'utente un'opzione per guardare un annuncio video per ricevere un prodotto premio, devi caricare il video. A questo scopo, crea un oggetto RewardLoadParams, associandolo all'oggetto SkuDetails che rappresenta il prodotto premio. Poi chiama il metodo loadRewardedSku() del client di fatturazione, passando l'oggetto RewardLoadParams e un oggetto RewardResponseListener.

Il listener RewardResponseListener riceve una notifica al termine del caricamento del video. L'ascoltatore viene avvisato anche se il video non è disponibile o se si verifica un altro errore, ad esempio un timeout del server.

Per mantenere le prestazioni del dispositivo durante il caricamento dei video associati ai prodotti con premio della tua app, tieni presente le seguenti best practice:

  • Carica al massimo tre SKU di prodotti premio alla volta.
  • Prova a caricare i video ogni volta che l'utente accede alla tua app. Questo passaggio ti aiuta a verificare se i video sono ancora caricati e disponibili.

  • Quando decidi quando caricare i video, scegli l'equilibrio tra utilizzo della larghezza di banda e reattività dell'app più adatto al tuo caso d'uso:

    • Carica i video al più presto dopo aver chiamato getSkuDetails() per il prodotto premio associato. La tua app rimane molto reattiva, ma potresti sprecare dati di rete caricando un video che l'utente non guarda mai.
    • Al più tardi, carica il video quando l'utente visita la pagina in cui deve essere visualizzato. In questo caso, l'app raramente spreca larghezza di banda, ma l'utente potrebbe dover attendere qualche istante prima che il pulsante per guardare il video diventi selezionabile.

Lo snippet di codice riportato di seguito mostra la procedura per caricare un annuncio video che viene riprodotto prima che l'utente riceva il prodotto con premio:

Kotlin

if (skuDetails.isRewarded()) {
    val params = RewardLoadParams.Builder()
            .setSkuDetails(skuDetails)
            .build()
    mBillingClient.loadRewardedSku(params.build(),
            object : RewardResponseListener {
        override fun onRewardResponse(@BillingResponse responseCode : Int) {
            if (responseCode == BillingResponse.OK) {
                // Enable the reward product, or make
                // any necessary updates to the UI.
            }
        }
    })
}

Java

if (skuDetails.isRewarded()) {
    RewardLoadParams.Builder params = RewardLoadParams.newBuilder();
    params.setSkuDetails(skuDetails);
    mBillingClient.loadRewardedSku(params.build(),
        new RewardResponseListener() {
            @Override
            public void onRewardResponse(int responseCode) {
                if (responseCode == BillingResponse.OK) {
                      // Enable the reward product, or make
                      // any necessary updates to the UI.
                  }
            }
        });
}

Offrire acquisti con premio agli utenti

Se la Libreria Fatturazione Google Play carica correttamente il video associato a un prodotto con premio, ovvero se RewardResponseListener riceve un responseCode di BillingResponse.OK, puoi avviare il flusso di fatturazione.

Per iniziare a riprodurre gli annunci per un prodotto premio, chiama launchBillingFlow(), come fai per tutti gli altri tipi di prodotti in-app. Anche se l'utente non effettua un acquisto diretto per ricevere un prodotto premio, devi comunque attivare il flusso di fatturazione in modo che possa ottenere e utilizzare il prodotto.

Consumare l'acquisto

Per comunicare al tuo client di fatturazione che un utente ha ricevuto e utilizzato un prodotto con premio, gestisci l'acquisto nel metodo onPurchasesUpdated() del listener del client di fatturazione. Tieni presente che gli acquisti con premio devono essere consumati.

Testare i prodotti premio

Per testare il caricamento degli annunci video e la fornitura di prodotti con premio agli utenti da parte della tua app, utilizza i tester con licenza, che per impostazione predefinita visualizzano annunci di prova anziché annunci reali. Per scoprire come configurare gli account per questi tester, consulta Testare un'app di Fatturazione Google Play.

Un altro metodo di test consiste nell'utilizzare l'ID prodotto android.test.reward. Questo prodotto specifico è un nome riservato in Fatturazione Google Play, quindi non devi aggiungerlo all'elenco dei prodotti in-app in Play Console.

Attenzione: quando testi i prodotti con premio della tua app, non utilizzare prodotti reali, altrimenti il tuo account potrebbe essere segnalato come spam o fraudolento.

Al termine del test, assicurati di sostituire android.test.reward con gli ID prodotto dei tuoi prodotti con premio effettivi prima di distribuire l'app di produzione agli utenti finali.

Diagramma del workflow del prodotto premio

Il seguente diagramma di sequenza mostra come l'utente, la tua app e la libreria Fatturazione Google Play collaborano per mostrare un annuncio video e concedere all'utente l'accesso a un prodotto con premio:

Diagramma di sequenza che mostra il protocollo dei prodotti-premio
Figura 1. Passaggi per completare l'acquisto di un prodotto premio utilizzando Fatturazione Google Play