Aggiungere funzionalità specifiche dei prodotti premio

Un metodo per usufruire dei vantaggi e dei prodotti in-app per gli utenti è creare prodotti con premio, ovvero elementi che gli utenti ricevono dopo aver guardato un video pubblicitario. Fornendo prodotti premio, consenti agli utenti di ricevere premi e vantaggi in-app senza che debbano effettuare acquisti diretti.

Questo documento spiega come implementare funzionalità specifiche per i prodotti premio. La sezione Diagramma del flusso di lavoro di questa pagina illustra il processo.

Identificare i prodotti premio della tua app

I prodotti premio hanno un valore di SkuType pari a 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 del prodotto. Per farlo, chiama querySkuDetailsAsync() con SkuType.INAPP come tipo di prodotto.

Dichiarare annunci adatti all'età

Per favorire il rispetto degli obblighi legali relativi a bambini e ragazzi e ai minorenni, tra cui il 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 destinati ai minori negli Stati Uniti e quali annunci sono rivolti agli utenti che non hanno raggiunto l'età minima richiesta nel loro paese. Il Centro assistenza AdMob spiega quando codificare le richieste di annunci per il trattamento per siti o servizi destinati ai minori e quando è opportuno eseguire il tagging per i trattamenti per utenti sotto l'età del consenso, nonché gli effetti di questa operazione.

Durante la creazione del client di fatturazione per la tua app, valuta se le richieste di annunci con premio devono essere trattate come rivolte ai minori o se devono essere rivolte a utenti di età inferiore a quella del consenso digitale. Se è necessario applicare queste restrizioni alle richieste di annunci, chiama i metodi setChildDirected() e setUnderAgeOfConsent(), trasmettendo 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 all'età del consenso digitale:

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();

Carica annunci video

Prima di mostrare all'utente la possibilità di guardare un annuncio video per ricevere un prodotto con premio, devi caricare il video. Per farlo, crea un oggetto RewardLoadParams, associandolo all'oggetto SkuDetails che rappresenta il prodotto premio. Quindi, chiama il metodo loadRewardedSku() del cliente di fatturazione, passando l'oggetto RewardLoadParams e un oggetto RewardResponseListener.

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

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

  • Carica al massimo tre SKU di prodotti premio alla volta.
  • Tenta di 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à delle app più adatto al tuo caso d'uso:

    • Carica i video subito dopo aver chiamato il numero getSkuDetails() per il prodotto premio associato. L'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 accede alla pagina in cui deve essere visualizzato. Raramente la tua app spreca larghezza di banda in questo caso, ma l'utente potrebbe dover attendere qualche istante prima che il pulsante per guardare il video diventi cliccabile.

Il seguente snippet di codice illustra la procedura per caricare un annuncio video riprodotto prima che l'utente riceva il prodotto 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 premio, ovvero se RewardResponseListener riceve responseCode per BillingResponse.OK, puoi avviare il flusso di fatturazione.

Per iniziare a riprodurre gli annunci relativi a un prodotto premio, chiami il 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 abilitare il flusso di fatturazione in modo che l'utente possa ottenere e utilizzare il prodotto.

Completa l'acquisto

Per notificare al cliente di fatturazione che un utente ha ricevuto e utilizzato un prodotto premio, gestisci l'acquisto con il metodo onPurchasesUpdated() dell'ascoltatore del cliente di fatturazione. Tieni presente che gli acquisti con premio devono essere consumati.

Testa i prodotti premio

Per verificare come la tua app carica gli annunci video e fornisce agli utenti prodotti premio, ricorri a tester autorizzati, che per impostazione predefinita ricevono annunci di prova anziché quelli reali. Per informazioni su come configurare gli account per questi tester, consulta la pagina Testare gli utenti di 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 è necessario aggiungerlo al tuo elenco di prodotti in-app in Play Console.

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

Al termine del test, tuttavia, assicurati di sostituire android.test.reward con gli ID prodotto dei prodotti premio effettivi prima di eseguire il deployment dell'app di produzione per gli utenti finali.

Diagramma del flusso di lavoro dei prodotti premio

Il seguente diagramma sequenza mostra in che modo l'utente, la tua app e la Libreria Fatturazione Google Play interagiscono per mostrare un annuncio video e concedere all'utente l'accesso a un prodotto 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