Annunci nativi

Gli annunci nativi sono asset annuncio che vengono presentati agli utenti tramite componenti dell'interfaccia utente nativi della piattaforma. Vengono mostrati utilizzando gli stessi tipi di visualizzazioni con cui stai già creando i tuoi layout e possono essere formattati in base al design visivo della tua app.

Quando viene caricato un annuncio nativo, la tua app riceve un oggetto annuncio contenente gli asset e sarà responsabile della loro visualizzazione, anziché l'SDK Google Mobile Ads.

In linea di massima, l'implementazione degli annunci nativi prevede due fasi: caricare un annuncio utilizzando l'SDK e poi visualizzare i contenuti dell'annuncio nella tua app.

Questa pagina mostra come utilizzare l'SDK per caricare annunci nativi. Suggerimento: scopri di più sugli annunci nativi nel nostro Playbook sugli annunci nativi.

Puoi anche consultare alcune storie di successo dei clienti: case study 1, case study 2.

Prerequisiti

• Completa la Guida introduttiva.

Effettua sempre test con annunci di prova

Quando crei e testi le tue app, assicurati di utilizzare annunci di prova anziché annunci di produzione pubblicati.

Il modo più semplice per caricare gli annunci di prova è utilizzare il nostro ID unità pubblicitaria di prova dedicato per gli annunci nativi su Android:

ca-app-pub-3940256099942544/2247696110

È stato configurato appositamente per restituire annunci di prova per ogni richiesta e puoi usarlo nelle tue app durante la programmazione, i test e il debug. Assicurati solo di sostituirlo con il tuo ID unità pubblicitaria prima di pubblicare l'app.

Per saperne di più sul funzionamento degli annunci di prova dell'SDK Google Mobile Ads, consulta Annunci di prova.

Caricare gli annunci

Gli annunci nativi vengono caricati con la classe AdLoader, che ha la propria Builder classe per personalizzarla durante la creazione. Aggiungendo ascoltatori al AdLoader durante la creazione, un'app specifica quali tipi di annunci nativi è pronta a ricevere. AdLoader richiede quindi solo questi tipi.

Creare un AdLoader

Punto chiave: esegui tutte le chiamate all'SDK Mobile Ads nel thread principale.

Il seguente codice mostra come creare un AdLoader che può caricare annunci nativi:

Java

AdLoader adLoader = new AdLoader.Builder(context, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
        @Override
        public void onNativeAdLoaded(NativeAd nativeAd) {
            // Show the ad.
        }
    })
    .withAdListener(new AdListener() {
        @Override
        public void onAdFailedToLoad(LoadAdError adError) {
            // Handle the failure by logging, altering the UI, and so on.
        }
    })
    .withNativeAdOptions(new NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110}")
    .forNativeAd { ad : NativeAd ->
        // Show the ad.
    }
    .withAdListener(object : AdListener() {
        override fun onAdFailedToLoad(adError: LoadAdError) {
            // Handle the failure.
        }
    })
    .withNativeAdOptions(NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build()

Avviso: il tentativo di caricare un nuovo annuncio dal metodo onAdFailedToLoad() è fortemente sconsigliato. Se devi caricare un annuncio da onAdFailedToLoad(), limita i nuovi tentativi di caricamento degli annunci per evitare richieste di annunci continue non riuscite in situazioni quali una connettività di rete limitata.

Il metodo forNativeAd() è responsabile della preparazione di AdLoader per il formato NativeAd. Quando un annuncio viene caricato correttamente, viene chiamato il metodo onNativeAdLoaded() dell'oggetto ascoltatore.

Impostare un AdListener con AdLoader (facoltativo)

Quando viene creato il file AdLoader, la funzione withAdListener imposta un AdListener per il caricatore. Il metodo accetta un AdListener come unico parametro, che riceve callback dal AdLoader quando si verificano gli eventi del ciclo di vita dell'annuncio:

Java

.withAdListener(new AdListener() {
    // AdListener callbacks can be overridden here.
})

Kotlin

.withAdListener(object : AdListener() {
    // AdListener callbacks can be overridden here.
})

Richiedi annunci

Suggerimento: puoi utilizzare le chiamate di caricamento degli annunci per creare una cache di annunci pre caricati prima di intenderne la pubblicazione, in modo che gli annunci possano essere mostrati senza latenza quando necessario. Poiché gli annunci scadono dopo un'ora, devi svuotare questa cache e ricaricare con nuovi annunci ogni ora.

Una volta completata la creazione di un AdLoader, è il momento di utilizzarlo per richiedere gli annunci. Esistono due metodi disponibili: loadAd() e loadAds().

Punto chiave: il metodo loadAds() funziona attualmente solo con Google Ads. Per gli annunci mediati, utilizza invece loadAd().

loadAd()

Questo metodo invia una richiesta per un singolo annuncio.

Java

adLoader.loadAd(new AdRequest.Builder().build());

Kotlin

adLoader.loadAd(AdRequest.Builder().build())

loadAds()

Questo metodo invia una richiesta per più annunci (fino a cinque):

Java

adLoader.loadAds(new AdRequest.Builder().build(), 3);

Kotlin

adLoader.loadAds(AdRequest.Builder().build(), 3)

Entrambi i metodi accettano un oggetto AdRequest come primo parametro. Si tratta della stessa classe AdRequest utilizzata da banner e interstitial, e puoi utilizzare i metodi della classe AdRequest per aggiungere informazioni sul targeting, come faresti con gli altri formati degli annunci.

Carica più annunci (facoltativo)

Il metodo loadAds() accetta un parametro aggiuntivo: il numero di annunci che l'SDK deve tentare di caricare per la richiesta. Il numero massimo è 5 e non è garantito che l'SDK restituirà il numero esatto di annunci richiesti.

Gli annunci Google restituiti saranno tutti diversi tra loro, anche se non è garantito che gli annunci provenienti dall'inventario riservato o da acquirenti di terze parti siano unici.

Non utilizzare il metodo loadAds() se utilizzi la mediazione, poiché le richieste di più annunci nativi al momento non funzionano per gli ID unità pubblicitaria configurati per la mediazione.

Callback

Dopo una chiamata a loadAd(), viene eseguito un singolo callback ai metodi di listener definiti in precedenza per pubblicare l'oggetto annuncio nativo o segnalare un errore.

Dopo una chiamata a loadAds(), vengono eseguiti più di questi callback (almeno uno e non più del numero di annunci richiesti). Le app che richiedono più annunci devono chiamare AdLoader.isLoading() nelle implementazioni dei callback per determinare se il processo di caricamento è terminato.

Ecco un esempio che mostra come controllare isLoading() nel callback onNativeAdLoaded():

Java

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd nativeAd) {
        ...
        // some code that displays the ad.
        ...
        if (adLoader.isLoading()) {
            // The AdLoader is still loading ads.
            // Expect more adLoaded or onAdFailedToLoad callbacks.
        } else {
            // The AdLoader has finished loading ads.
        }
    }
}).build();
adLoader.loadAds(new AdRequest.Builder().build(), 3);

Kotlin

lateinit var adLoader: AdLoader
...
adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd {
        ...
        // some code that displays the ad.
        ...
        if (adLoader.isLoading) {
            // The AdLoader is still loading ads.
            // Expect more adLoaded or onAdFailedToLoad callbacks.
        } else {
            // The AdLoader has finished loading ads.
        }
    }.build()
adLoader.loadAds(AdRequest.Builder().build(), 3)

Svincola risorse

Assicurati di utilizzare il metodo destroy() sugli annunci nativi caricati. In questo modo vengono liberate le risorse utilizzate e vengono evitate perdite di memoria.

Punto chiave: destroy() deve essere chiamato per tutti gli annunci, anche se non sono stati utilizzati o a cui non è stato fatto riferimento.

Assicurati che tutti i riferimenti a NativeAd vengano distrutti nel metodo NativeAd dell'attività.

Nel callback onNativeAdLoaded, assicurati di distruggere gli annunci nativi esistenti che verranno dereferenziati.

Un'altra verifica della chiave è se l'attività viene eliminata e, in questo caso, richiama destroy() sull'annuncio restituito e restituisci immediatamente:

Java

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd nativeAd) {
        // If this callback occurs after the activity is destroyed, you
        // must call destroy and return or you may get a memory leak.
        // Note `isDestroyed()` is a method on Activity.
        if (isDestroyed()) {
            nativeAd.destroy();
            return;
        }
        ...
    }
}).build();

Kotlin

lateinit var adLoader: AdLoader
...
adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd { nativeAd ->
        // If this callback occurs after the activity is destroyed, you
        // must call destroy and return or you may get a memory leak.
        // Note `isDestroyed` is a method on Activity.
        if (isDestroyed) {
            nativeAd.destroy()
            return@forNativeAd
        }
        ...
    }.build()

Best practice

Segui queste regole quando carichi gli annunci.

• Le app che utilizzano annunci nativi in un elenco devono eseguire la memorizzazione nella cache dell'elenco di annunci.

• Quando memorizzi nella cache gli annunci, svuota la cache e ricarica dopo un'ora.

• Non chiamare loadAd() o loadAds() su un AdLoader finché il caricamento della prima richiesta non è terminato.

• Limita la memorizzazione nella cache degli annunci nativi solo a ciò che è necessario. Ad esempio, durante il pre-caching, memorizza nella cache solo gli annunci immediatamente visibili sullo schermo. Gli annunci nativi hanno un'impronta in memoria elevata e la loro memorizzazione nella cache senza distruggerli comporta un utilizzo eccessivo della memoria.

• Elimina gli annunci nativi quando non sono più in uso.

Accelerazione hardware per gli annunci video

Affinché gli annunci video vengano visualizzati correttamente nelle visualizzazioni degli annunci nativi, deve essere attivata l'accelerazione hardware.

L'accelerazione hardware è abilitata per impostazione predefinita, ma alcune app potrebbero decidere di disattivarla. Se questo vale per la tua app, ti consigliamo di attivare l'accelerazione hardware per le classi Attività che utilizzano gli annunci.

Attivazione dell'accelerazione hardware

Se la tua app non si comporta correttamente con l'accelerazione hardware attivata a livello globale, puoi controllarla anche per le singole attività. Per attivare o disattivare l'accelerazione hardware, utilizza l'attributo android:hardwareAccelerated per gli elementi <application> e <activity> nel AndroidManifest.xml. L'esempio seguente abilita l'accelerazione hardware per l'intera app, ma la disabilita per un'attività:

<application android:hardwareAccelerated="true">
    <!-- For activities that use ads, hardwareAcceleration should be true. -->
    <activity android:hardwareAccelerated="true" />
    <!-- For activities that don't use ads, hardwareAcceleration can be false. -->
    <activity android:hardwareAccelerated="false" />
</application>

Per ulteriori informazioni sulle opzioni per il controllo dell'accelerazione hardware, consulta la guida sull'accelerazione hardware. Tieni presente che non è possibile attivare l'accelerazione hardware per le singole visualizzazioni degli annunci se l'attività è disattivata, pertanto l'accelerazione hardware deve essere attivata per l'attività stessa.

Mostrare l'annuncio

Dopo aver caricato un annuncio, non resta che mostrarlo agli utenti. Consulta la nostra guida Native Advanced per scoprire come.