Annunci nativi

Gli annunci nativi sono asset dell'annuncio presentati agli utenti tramite i componenti dell'interfaccia utente nativi della piattaforma. Vengono visualizzati utilizzando gli stessi tipi di viste con cui stai già creando i layout e possono essere formattati in modo da corrispondere al design visivo dell'esperienza utente in cui si trovano. In termini di programmazione, questo significa che quando viene caricato un annuncio nativo, la tua app riceve un oggetto NativeAd che contiene i suoi asset e l'app (anziché l'SDK Google Mobile Ads) è quindi responsabile della loro visualizzazione.

In generale, ci sono due parti per implementare correttamente gli annunci nativi: il caricamento di un annuncio tramite l'SDK e la visualizzazione dei relativi contenuti nell'app. Questa pagina riguarda l'utilizzo dell'SDK per caricare annunci nativi.

Prerequisiti

Carica un annuncio

Gli annunci nativi vengono caricati tramite la classe AdLoader, che ha la propria classe Builder per personalizzarla durante la creazione. L'aggiunta di ascoltatori al AdLoader durante la creazione di un'app specifica il tipo di annunci nativi che è pronto a ricevere. Il modello AdLoader richiede poi solo questi tipi.

Crea un Adload

Il codice seguente illustra come creare un AdLoader in grado di 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 by logging, altering the UI, and so on.
        }
    })
    .withNativeAdOptions(NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build()

Prepararsi per il formato NativeAd

Il primo metodo descritto sopra è responsabile della preparazione di AdLoader per il formato NativeAd:

forNativeAd()
Questo metodo configura il AdLoader per richiedere gli annunci nativi. Quando un annuncio è stato caricato correttamente, viene richiamato il metodo onNativeAdLoaded() dell'oggetto listener.

Quando AdLoader effettua una richiesta di annuncio, Google seleziona e restituisce l'annuncio che massimizza il rendimento del publisher.

Usare Ad Locator con un Adload

Durante la creazione di AdLoader riportata sopra, la funzione withAdListener imposta un elemento AdListener.

Questo passaggio è facoltativo. Il metodo utilizza un AdListener come parametro unico, che riceve i callback da AdLoader quando si verificano eventi del ciclo di vita degli annunci:

Java

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

Kotlin

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

Caricamento degli annunci in corso...

Dopo aver completato la creazione di una AdLoader, è il momento di utilizzarla per caricare gli annunci. Esistono due metodi per farlo: loadAd() e loadAds().

Il metodo loadAd() invia una richiesta per un singolo annuncio:

loadAd()
Questo metodo invia una richiesta per un singolo annuncio.

Java

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

Kotlin

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

Il metodo loadAds() invia una richiesta per più annunci (fino a 5):

Java

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

Kotlin

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

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

loadAds() utilizza un parametro aggiuntivo: il numero di annunci che l'SDK deve tentare di caricare per la richiesta. Questo numero è limitato a un massimo di cinque e non è garantito che l'SDK restituisca il numero esatto di annunci richiesti. Se più annunci vengono restituiti da una chiamata al numero loadAds(), saranno diversi.

Dopo una chiamata a loadAd(), verrà effettuato un singolo callback sui metodi di listener definiti sopra per pubblicare l'oggetto dell'annuncio nativo o segnalare un errore.

Dopo una chiamata al numero loadAds(), verranno effettuati diversi callback (almeno uno e non più del numero di annunci richiesto). Le app che richiedono più annunci devono chiamare AdLoader.isLoading() nelle implementazioni di 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)

Eseguire la pulizia

Assicurati di utilizzare il metodo destroy() negli annunci nativi caricati. In questo modo si liberano risorse utilizzate e si evitano perdite di memoria.

Assicurati che tutti i riferimenti NativeAd vengano eliminati nel metodo onDestroy() delle tue attività.

Nel callback onNativeAdLoaded, assicurati di eliminare l'eventuale annuncio nativo esistente a cui verrà fatto riferimento.

Un altro controllo fondamentale è se l'attività viene distrutta e, in tal caso, chiama destroy() sull'annuncio restituito per tornare 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()

Eseguire sempre i test con gli annunci di prova

Durante la creazione e il test delle tue app, assicurati di utilizzare annunci di prova anziché annunci attivi di produzione. In caso contrario, l'account potrebbe essere sospeso.

Il modo più semplice per caricare gli annunci di prova è utilizzare l'ID dell'unità pubblicitaria di prova dedicata per gli annunci nativi avanzati su Android:

ca-app-pub-3940256099942544/2247696110

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

Per maggiori informazioni su come funzionano gli annunci di prova dell'SDK Mobile Ads, consulta Testa annunci.

Quando richiedere gli annunci

Le applicazioni che pubblicano annunci nativi possono richiederle in anticipo rispetto al momento in cui verranno effettivamente visualizzate. In molti casi, questa è la pratica consigliata. Un'app che mostra un elenco di elementi con annunci nativi uniti, ad esempio, può caricare annunci nativi per l'intero elenco, sapendo che alcuni verranno mostrati solo dopo che l'utente scorre la visualizzazione e altri potrebbero non essere visualizzati affatto.

Accelerazione hardware per gli annunci video

Affinché gli annunci video vengano visualizzati correttamente nelle visualizzazioni degli annunci nativi, è necessario attivare l'accelerazione hardware.

L'accelerazione hardware è abilitata per impostazione predefinita, ma alcune app potrebbero decidere di disattivarla. Se questo è il tuo caso, ti consigliamo di attivare l'accelerazione hardware per le classi di 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 per le singole attività. Per attivare o disattivare l'accelerazione hardware, puoi utilizzare l'attributo android:hardwareAccelerated per gli elementi <application> e <activity> in AndroidManifest.xml. L'esempio seguente consente 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>

Consulta la guida all'accelerazione HW per saperne di più sulle opzioni per il controllo dell'accelerazione hardware. Tieni presente che non è possibile attivare le visualizzazioni hardware di singoli annunci per l'accelerazione hardware se l'attività è disattivata, quindi l'attività stessa deve avere l'accelerazione hardware abilitata.

Mostra un annuncio nativo

Dopo aver caricato un annuncio, non rimane che mostrarlo agli utenti. Consulta la nostra guida avanzata per gli annunci nativi per scoprire come fare.

,

Gli annunci nativi sono asset dell'annuncio presentati agli utenti tramite i componenti dell'interfaccia utente nativi della piattaforma. Vengono visualizzati utilizzando gli stessi tipi di viste con cui stai già creando i layout e possono essere formattati in modo da corrispondere al design visivo dell'esperienza utente in cui si trovano. In termini di programmazione, questo significa che quando viene caricato un annuncio nativo, la tua app riceve un oggetto NativeAd che contiene i suoi asset e l'app (anziché l'SDK Google Mobile Ads) è quindi responsabile della loro visualizzazione.

In generale, ci sono due parti per implementare correttamente gli annunci nativi: il caricamento di un annuncio tramite l'SDK e la visualizzazione dei relativi contenuti nell'app. Questa pagina riguarda l'utilizzo dell'SDK per caricare annunci nativi.

Prerequisiti

Carica un annuncio

Gli annunci nativi vengono caricati tramite la classe AdLoader, che ha la propria classe Builder per personalizzarla durante la creazione. L'aggiunta di ascoltatori al AdLoader durante la creazione di un'app specifica il tipo di annunci nativi che è pronto a ricevere. Il modello AdLoader richiede poi solo questi tipi.

Crea un Adload

Il codice seguente illustra come creare un AdLoader in grado di 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 by logging, altering the UI, and so on.
        }
    })
    .withNativeAdOptions(NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build()

Prepararsi per il formato NativeAd

Il primo metodo descritto sopra è responsabile della preparazione di AdLoader per il formato NativeAd:

forNativeAd()
Questo metodo configura il AdLoader per richiedere gli annunci nativi. Quando un annuncio è stato caricato correttamente, viene richiamato il metodo onNativeAdLoaded() dell'oggetto listener.

Quando AdLoader effettua una richiesta di annuncio, Google seleziona e restituisce l'annuncio che massimizza il rendimento del publisher.

Usare Ad Locator con un Adload

Durante la creazione di AdLoader riportata sopra, la funzione withAdListener imposta un elemento AdListener.

Questo passaggio è facoltativo. Il metodo utilizza un AdListener come parametro unico, che riceve i callback da AdLoader quando si verificano eventi del ciclo di vita degli annunci:

Java

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

Kotlin

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

Caricamento degli annunci in corso...

Dopo aver completato la creazione di una AdLoader, è il momento di utilizzarla per caricare gli annunci. Esistono due metodi per farlo: loadAd() e loadAds().

Il metodo loadAd() invia una richiesta per un singolo annuncio:

loadAd()
Questo metodo invia una richiesta per un singolo annuncio.

Java

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

Kotlin

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

Il metodo loadAds() invia una richiesta per più annunci (fino a 5):

Java

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

Kotlin

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

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

loadAds() utilizza un parametro aggiuntivo: il numero di annunci che l'SDK deve tentare di caricare per la richiesta. Questo numero è limitato a un massimo di cinque e non è garantito che l'SDK restituisca il numero esatto di annunci richiesti. Se più annunci vengono restituiti da una chiamata al numero loadAds(), saranno diversi.

Dopo una chiamata a loadAd(), verrà effettuato un singolo callback sui metodi di listener definiti sopra per pubblicare l'oggetto dell'annuncio nativo o segnalare un errore.

Dopo una chiamata al numero loadAds(), verranno effettuati diversi callback (almeno uno e non più del numero di annunci richiesto). Le app che richiedono più annunci devono chiamare AdLoader.isLoading() nelle implementazioni di 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)

Eseguire la pulizia

Assicurati di utilizzare il metodo destroy() negli annunci nativi caricati. In questo modo si liberano risorse utilizzate e si evitano perdite di memoria.

Assicurati che tutti i riferimenti NativeAd vengano eliminati nel metodo onDestroy() delle tue attività.

Nel callback onNativeAdLoaded, assicurati di eliminare l'eventuale annuncio nativo esistente a cui verrà fatto riferimento.

Un altro controllo fondamentale è se l'attività viene distrutta e, in tal caso, chiama destroy() sull'annuncio restituito per tornare 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()

Eseguire sempre i test con gli annunci di prova

Durante la creazione e il test delle tue app, assicurati di utilizzare annunci di prova anziché annunci attivi di produzione. In caso contrario, l'account potrebbe essere sospeso.

Il modo più semplice per caricare gli annunci di prova è utilizzare l'ID dell'unità pubblicitaria di prova dedicata per gli annunci nativi avanzati su Android:

ca-app-pub-3940256099942544/2247696110

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

Per maggiori informazioni su come funzionano gli annunci di prova dell'SDK Mobile Ads, consulta Testa annunci.

Quando richiedere gli annunci

Le applicazioni che pubblicano annunci nativi possono richiederle in anticipo rispetto al momento in cui verranno effettivamente visualizzate. In molti casi, questa è la pratica consigliata. Un'app che mostra un elenco di elementi con annunci nativi uniti, ad esempio, può caricare annunci nativi per l'intero elenco, sapendo che alcuni verranno mostrati solo dopo che l'utente scorre la visualizzazione e altri potrebbero non essere visualizzati affatto.

Accelerazione hardware per gli annunci video

Affinché gli annunci video vengano visualizzati correttamente nelle visualizzazioni degli annunci nativi, è necessario attivare l'accelerazione hardware.

L'accelerazione hardware è abilitata per impostazione predefinita, ma alcune app potrebbero decidere di disattivarla. Se questo è il tuo caso, ti consigliamo di attivare l'accelerazione hardware per le classi di 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 per le singole attività. Per attivare o disattivare l'accelerazione hardware, puoi utilizzare l'attributo android:hardwareAccelerated per gli elementi <application> e <activity> in AndroidManifest.xml. L'esempio seguente consente 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>

Consulta la guida all'accelerazione HW per saperne di più sulle opzioni per il controllo dell'accelerazione hardware. Tieni presente che non è possibile attivare le visualizzazioni hardware di singoli annunci per l'accelerazione hardware se l'attività è disattivata, quindi l'attività stessa deve avere l'accelerazione hardware abilitata.

Mostra un annuncio nativo

Dopo aver caricato un annuncio, non rimane che mostrarlo agli utenti. Consulta la nostra guida avanzata per gli annunci nativi per scoprire come fare.