Formati di annunci nativi personalizzati

Formati degli annunci nativi personalizzati

Oltre ai formati nativi definiti dal sistema, i publisher di Ad Manager hanno la possibilità di creare i propri formati degli annunci nativi definendo elenchi personalizzati di asset. Si tratta dei formati degli annunci nativi personalizzati e possono essere utilizzati con gli annunci riservati. In questo modo, i publisher possono trasmettere dati strutturati arbitrari alle proprie app. Questi annunci sono rappresentati dall'oggetto NativeCustomFormatAd.

Caricare formati degli annunci nativi personalizzati

Questa guida spiega come caricare e visualizzare i formati degli annunci nativi personalizzati.

Creare un AdLoader

Come per gli annunci nativi, i formati degli annunci nativi personalizzati vengono caricati utilizzando la classe AdLoader:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
          @Override
          public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
              // Show the custom format and record an impression.
          }
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String s) {
              // Handle the click action
          }
      })
    .withAdListener( ... )
    .withNativeAdOptions( ... )
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
        .forCustomFormatAd("10063170",
            { ad ->
                // Show the custom format and record an impression.
            },
            { ad, s ->
            // Handle the click action
            })
        .withAdListener( ... )
        .withNativeAdOptions( ... )
        .build()

Il metodo forCustomFormatAd configura AdLoader per richiedere formati degli annunci personalizzati nativ. Al metodo vengono passati tre parametri:

• L'ID del formato dell'annuncio nativo personalizzato che AdLoader deve richiedere. A ogni formato dell'annuncio nativo personalizzato è associato un ID. Questo parametro indica il formato che l'app vuole che AdLoader richieda.
• Un OnCustomFormatAdLoadedListener da richiamare quando un annuncio è stato caricato correttamente.
• Un valore facoltativo OnCustomClickListener da richiamare quando l'utente tocca o fa clic sull'annuncio. Per saperne di più su questo ascoltatore, consulta la sezione "Gestione di clic e impressioni" di seguito.

Poiché una singola unità pubblicitaria può essere configurata per pubblicare più di un formato della creatività, forCustomFormatAd può essere chiamata più volte con ID formato univoci per preparare il caricamento degli annunci per più di un possibile formato dell'annuncio nativo personalizzato.

Nota: forNativeAd e forCustomFormatAd possono essere utilizzati contemporaneamente con un singolo AdLoader se hai un'unità pubblicitaria configurata per pubblicare più formati degli annunci.

ID formato dell'annuncio nativo personalizzato

L'ID formato utilizzato per identificare un formato dell'annuncio nativo personalizzato si trova nella UI di Ad Manager nella sezione Nativo del menu a discesa Pubblicazione:

Ogni ID formato dell'annuncio nativo personalizzato viene visualizzato accanto al nome. Se fai clic su uno dei nomi, viene visualizzata una schermata dei dettagli che mostra informazioni sui campi del formato:

Da qui, i singoli campi possono essere aggiunti, modificati e rimossi. Prendi nota del nome di ogni risorsa. Il nome è la chiave utilizzata per recuperare i dati di ogni asset quando viene visualizzato il formato dell'annuncio nativo personalizzato.

Pubblicare formati degli annunci nativi personalizzati

I formati degli annunci nativi personalizzati sono diversi da quelli definiti dal sistema in quanto i publisher hanno la possibilità di definire il proprio elenco di asset che compongono un annuncio. Pertanto, la procedura per la visualizzazione di uno di questi formati è diversa da quella per i formati definiti dal sistema in alcuni modi:

1. Poiché la classe NativeCustomFormatAd è progettata per gestire qualsiasi formato di annunci nativi personalizzati definito in Ad Manager, non dispone di "getter" denominati per gli asset. Offre invece metodi come getText e getImage che prendono il nome del campo come parametro.
2. Non esiste una classe di visualizzazione dell'annuncio dedicata come NativeAdView da utilizzare con NativeCustomFormatAd. Puoi utilizzare qualsiasi layout che abbia senso per la tua esperienza utente.
3. Poiché non esiste una classe ViewGroup dedicata, non è necessario registrare nessuna delle visualizzazioni utilizzate per visualizzare gli asset dell'annuncio. In questo modo risparmi alcune righe di codice durante la visualizzazione dell'annuncio, ma dovrai anche fare un po' di lavoro in più per gestire i clic in un secondo momento.

Ecco un esempio di funzione che mostra un NativeCustomFormatAd:

Java

public void displayCustomFormatAd (ViewGroup parent,
                                     NativeCustomFormatAd customFormatAd) {
    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    View adView = inflater.inflate(R.layout.custom_format_ad, parent);

    // Locate the TextView that will hold the value for "Headline" and
    // set its text.
    TextView myHeadlineView = (TextView) adView.findViewById(R.id.headline);
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    Button myMainImageView = (ImageView) adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").getDrawable());

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Kotlin

public fun displayCustomFormatAd (parent: ViewGroup,
                                customFormatAd: NativeCustomFormatAd) {
    val adView = layoutInflater
            .inflate(R.layout.ad_simple_custom_format, null)

    val myHeadlineView = adView.findViewById<TextView>(R.id.headline)
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    val myMainImageView = adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").drawable);

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Rendering dell'icona Scegli Tu!

Nell'ambito del supporto del Digital Services Act (DSA), gli annunci basati su prenotazione pubblicati nello Spazio economico europeo (SEE) richiedono un' icona Scegli Tu! e un link alla pagina Su questo annuncio di Google. Quando implementi annunci nativi personalizzati, sei responsabile del rendering dell'icona Scegli Tu!. Ti consigliamo di eseguire le operazioni per eseguire il rendering e impostare il listener di clic per l'icona Scegli Tu! durante il rendering degli asset annuncio principali.

Nell'esempio seguente si presume che tu abbia definito un elemento <ImageView /> nella gerarchia della visualizzazione per contenere il logo Scegli Tu!.

Importante: imposta l'icona Scegli tu! di almeno 15 x 15 pixel.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android">
    <ImageView
        android:id="@+id/adChoices"
        android:layout_width="15dp"
        android:layout_height="15dp"
        android:adjustViewBounds="true"
        android:contentDescription="AdChoices icon." />
</LinearLayout>

Gli esempi riportati di seguito visualizzano l'icona Scegli Tu! e configurano il comportamento appropriato dei clic.

Java

private AdSimpleCustomTemplateBinding customTemplateBinding;

private void populateAdView(final NativeCustomFormatAd nativeCustomFormatAd) {
  // Render the AdChoices icon.
  String adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW;
  NativeAd.Image adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey);
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.setVisibility(View.GONE);
  } else {
    customTemplateBinding.adChoices.setVisibility(View.VISIBLE);
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.getDrawable());

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            nativeCustomFormatAd.performClick(adChoicesKey);
          }
        });
  }
  ...
}

Kotlin

private lateinit var customTemplateBinding: AdSimpleCustomTemplateBinding

private fun populateAdView(nativeCustomFormatAd: NativeCustomFormatAd) {
  // Render the AdChoices icon.
  val adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW
  val adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey)
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.visibility = View.GONE
  } else {
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.drawable)
    customTemplateBinding.adChoices.visibility = View.VISIBLE

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener {
      nativeCustomFormatAd.performClick(adChoicesKey)
    }
  }
  ...
}

Punto chiave: se utilizzi il controllo del download delle immagini per richiedere solo gli URL delle immagini, l'asset Scegli Tu! rispetta questa impostazione e restituisce solo l'URL immagine.

Video nativo per i formati degli annunci nativi personalizzati

Quando crei un formato personalizzato, hai la possibilità di renderlo idoneo per i video.

Nell'implementazione dell'app, puoi utilizzare NativeCustomFormatAd.getMediaContent() per recuperare i contenuti multimediali. Quindi, chiama setMediaContent() per impostare i contenuti multimediali nella visualizzazione dei contenuti multimediali. Se l'annuncio non include contenuti video, crea piani alternativi per mostrarlo senza video.

Nota: a differenza degli annunci nativi, che contengono un'immagine nella visualizzazione multimediale quando il video non è disponibile, la visualizzazione multimediale di un annuncio nativo personalizzato non contiene contenuti se non include un video.

L'esempio seguente verifica se l'annuncio include contenuti video e mostra un'immagine al suo posto se non è disponibile un video:

Java

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(final NativeCustomFormatAd ad) {

  MediaContent mediaContent = ad.getMediaContent();

  // Assumes you have a FrameLayout in your view hierarchy with the id media_placeholder.
  FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    MediaView mediaView = new MediaView(mediaPlaceholder.getContext());
    mediaView.setMediaContent(mediaContent);
    mediaPlaceholder.addView(mediaView);

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    VideoController vc = mediaContent.getVideoController();
    vc.setVideoLifecycleCallbacks(
        new VideoController.VideoLifecycleCallbacks() {
          @Override
          public void onVideoEnd() {
            // Publishers should allow native ads to complete video playback before
            // refreshing or replacing them with another ad in the same UI location.
            super.onVideoEnd();
          }
        });
  } else {
    ImageView mainImage = new ImageView(this);
    mainImage.setAdjustViewBounds(true);
    mainImage.setImageDrawable(ad.getImage("MainImage").getDrawable());
    mediaPlaceholder.addView(mainImage);
    mainImage.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View view) {
            ad.performClick("MainImage");
          }
        });
  }
}

Kotlin

// Called when a custom native ad loads.
NativeCustomFormatAd.OnCustomFormatAdLoadedListener { ad ->

  val mediaContent = ad.mediaContent

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    val mediaView = MediaView(mediaPlaceholder.getContest())
    mediaView.mediaContent = mediaContent

    val videoController = mediaContent.videoController

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    if (videoController != null) {
      videoController.videoLifecycleCallbacks =
        object : VideoController.VideoLifecycleCallbacks() {
          override fun onVideoEnd() {
            // Publishers should allow native ads to complete video playback before refreshing
            // or replacing them with another ad in the same UI location.
            super.onVideoEnd()
          }
        }
    }
  } else {
    val mainImage = ImageView(this)
    mainImage.adjustViewBounds = true
    mainImage.setImageDrawable(ad.getImage("MainImage")?.drawable)

    mainImage.setOnClickListener { ad.performClick("MainImage") }
    customTemplateBinding.simplecustomMediaPlaceholder.addView(mainImage)
  }
}

Per saperne di più su come personalizzare l'esperienza video di un annuncio nativo personalizzato, consulta MediaContent.

Scarica l'esempio di rendering personalizzato di Ad Manager per un esempio pratico di video nativi in azione.

Clic e impressioni dei formati degli annunci nativi personalizzati

Con i formati degli annunci nativi personalizzati, è responsabilità della tua app registrare le impressioni e segnalare gli eventi di clic all'SDK Google Mobile Ads.

Registrare le impressioni

Per registrare un'impressione per un annuncio con formato personalizzato, chiama il metodo recordImpression su NativeCustomFormatAd corrispondente:

myCustomFormatAd.recordImpression();

Se la tua app chiama accidentalmente il metodo due volte per lo stesso annuncio, l'SDK impedisce automaticamente la registrazione di un'impressione duplicata per una singola richiesta.

Clic sui report

Per segnalare all'SDK che si è verificato un clic in una visualizzazione della risorsa, chiama il metodo performClick su NativeCustomFormatAd corrispondente e passa il nome della risorsa su cui è stato fatto clic. Ad esempio, se nel tuo formato personalizzato hai una risorsa denominata "MainImage" e vuoi registrare un clic sul ImageView corrispondente a questa risorsa, il codice sarà il seguente:

myCustomFormatAd.performClick("MainImage");

Tieni presente che non è necessario chiamare questo metodo per ogni visualizzazione associata al tuo annuncio. Se avessi un altro campo denominato "Caption" che doveva essere visualizzato, ma su cui l'utente non ha fatto clic o tocco, la tua app non avrebbe bisogno di chiamare performClick per la visualizzazione della risorsa.

Rispondere alle azioni personalizzate dei clic

Quando viene eseguito un clic su un annuncio in formato personalizzato, sono possibili tre risposte dell'SDK, tentate in questo ordine:

1. Richiama OnCustomClickListener da AdLoader, se è stato fornito.
2. Per ciascuno degli URL dei link diretti dell'annuncio, prova a individuare un risolutore dei contenuti e avvia il primo che viene risolto.
3. Apri un browser e vai all'URL di destinazione tradizionale dell'annuncio.

Il metodo forCustomFormatAd accetta un OnCustomClickListener. Se invece passi un oggetto ascoltatore, l'SDK invoca il relativo metodo onCustomClick e non esegue altre azioni. Tuttavia, se passi un valore null come ascoltatore, l'SDK passa agli URL di destinazione e/o del link diretto registrati con l'annuncio.

Gli ascoltatori di clic personalizzati consentono alla tua app di decidere l'azione migliore da intraprendere in risposta a un clic, che si tratti di aggiornare l'interfaccia utente, avviare una nuova attività o semplicemente registrare il clic. Ecco un esempio che registra semplicemente che si è verificato un clic:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
        // Display the ad.
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String assetName) {
            Log.i("MyApp", "A custom click just happened for " + assetName + "!");
          }
      }).build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

A prima vista, potrebbe sembrare strano che esistano ascoltatori di clic personalizzati. Dopotutto, la tua app ha appena comunicato all'SDK che si è verificato un clic, quindi perché l'SDK dovrebbe girare e segnalarlo all'app?

Questo flusso di informazioni è utile per diversi motivi, ma soprattutto consente all'SDK di mantenere il controllo della risposta al clic. Può, ad esempio, eseguire automaticamente il ping degli URL di monitoraggio di terze parti impostati per la creatività e gestire altre attività in background, senza alcun codice aggiuntivo.