Formati di annunci nativi personalizzati

Formati di annunci nativi personalizzati

Oltre ai formati nativi definiti dal sistema, i publisher di Ad Manager hanno la possibilità di creare i propri formati di annunci nativi definendo elenchi personalizzati di asset. Questi sono chiamati formati di annunci nativi personalizzati e possono essere utilizzati con gli annunci prenotati. Ciò consente ai publisher di trasmettere dati strutturati arbitrari alle proprie app. Questi annunci sono rappresentati dall'oggetto NativeCustomFormatAd.

Carica formati di annunci nativi personalizzati

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

Crea un AdLoader

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

Java

AdLoader adLoader = new AdLoader.Builder(context, "/6499/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, "/6499/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 in modo che richieda formati di annunci nativi personalizzati. Al metodo vengono trasferiti tre parametri:

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

Poiché una singola unità pubblicitaria può essere impostata per pubblicare più di un formato della creatività, è possibile chiamare più volte forCustomFormatAd con ID formato univoci per preparare il caricatore di annunci per più di un possibile formato di annunci nativi personalizzato.

ID formato dell'annuncio nativo personalizzato

L'ID formato utilizzato per identificare un formato dell'annuncio nativo personalizzato è disponibile nell'interfaccia utente di Ad Manager nella sezione Nativo all'interno del menu a discesa Pubblicazione:

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

Da qui, puoi aggiungere, modificare e rimuovere singoli campi. Prendi nota del nome di ogni asset. Il nome è la chiave utilizzata per ottenere i dati per ogni asset quando visualizzi il tuo formato di annuncio nativo personalizzato.

Formati di annunci nativi personalizzati display

I formati di annunci nativi personalizzati sono diversi da quelli definiti dal sistema perché i publisher hanno la possibilità di definire il proprio elenco di asset che costituiscono un annuncio. Pertanto, il processo di visualizzazione di un formato differisce da quello definito dal sistema per alcuni aspetti:

  1. Poiché la classe NativeCustomFormatAd è pensata per gestire uno qualsiasi dei formati di annunci nativi personalizzati che definisci in Ad Manager, non ha nomi "getter" per gli asset. Offre invece metodi come getText e getImage che utilizzano il nome del campo come parametro.
  2. Non esiste un corso di visualizzazione dell'annuncio dedicato come NativeAdView da utilizzare con NativeCustomFormatAd. Puoi usare qualsiasi layout adatto alla tua esperienza utente.
  3. Poiché non esiste una classe ViewGroup dedicata, non è necessario registrare nessuna delle visualizzazioni che utilizzi per mostrare gli asset dell'annuncio. In questo modo puoi risparmiare alcune righe di codice al momento della visualizzazione dell'annuncio, ma devi anche svolgere un altro lavoro per gestire i clic in un secondo momento.

Ecco una funzione di esempio 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.
    ...
}

Visualizzare l'icona Scegli Tu!

Nell'ambito del Supporting the 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 Informazioni su questo annuncio di Google. Quando implementi annunci nativi personalizzati, sei responsabile del rendering dell'icona Scegli Tu!. Ti consigliamo di seguire alcuni passaggi per visualizzare e impostare l'ascolto dei clic per l'icona Scegli Tu! durante il rendering degli asset annuncio principali.

L'esempio seguente presuppone che tu abbia definito un elemento <ImageView /> nella gerarchia delle visualizzazioni che contenga il logo Scegli Tu!.

<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>

I seguenti esempi mostrano l'icona Scegli Tu! e configurano il comportamento dei clic appropriato.

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)
    }
  }
  ...
}

Video nativo per formati di annunci nativi personalizzati

Quando crei un formato personalizzato, puoi renderlo idoneo per i video.

Nell'implementazione dell'app, puoi utilizzare NativeCustomFormatAd.getMediaContent() per trasferire i contenuti multimediali. Quindi chiama il numero setMediaContent() per impostare i contenuti multimediali nella visualizzazione degli elementi multimediali. Se l'annuncio non include contenuti video, pensa a un modo alternativo per mostrarlo senza un video.

L'esempio riportato di seguito consente di verificare se l'annuncio include contenuti video e, se il video non è disponibile, viene mostrata un'immagine al suo posto:

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 ulteriori informazioni su come personalizzare l'esperienza video di un annuncio nativo personalizzato, consulta MediaContent.

Scarica l'esempio di rendering personalizzato di Ad Manager per avere un esempio funzionante di video nativo in azione.

Clic e impressioni per formati di annunci nativi personalizzati

Con i formati di annunci nativi personalizzati, la tua app è responsabile della registrazione delle impressioni e dei report sugli eventi di clic per l'SDK Google Mobile Ads.

Registra impressioni

Per registrare un'impressione per un annuncio in formato personalizzato, chiama il metodo recordImpression nell'elemento 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 dei report

Per segnalare all'SDK che è stato effettuato un clic su una visualizzazione di asset, chiama il metodo performClick nel NativeCustomFormatAd corrispondente e trasmetti il nome dell'asset su cui è stato fatto clic. Ad esempio, se avessi un asset nel tuo formato personalizzato chiamato "MainImage" e volessi registrare un clic su ImageView corrispondente a quell'asset, il codice sarà simile al seguente:

myCustomFormatAd.performClick("MainImage");

Tieni presente che non è necessario richiamare questo metodo per ogni visualizzazione associata all'annuncio. Se avessi un altro campo chiamato "Sottotitolo" che doveva essere visualizzato, ma non selezionato o toccato dall'utente, la tua app non avrebbe bisogno di chiamare performClick per la visualizzazione dell'asset.

Rispondere ad azioni di clic personalizzate

Quando viene eseguito un clic su un annuncio con formato personalizzato, l'SDK esegue tre possibili risposte in questo ordine:

  1. Richiama OnCustomClickListener da AdLoader, se ne è stato fornito uno.
  2. Per ogni URL link diretto dell'annuncio, prova a individuare un resolver di contenuti e avvia il primo che risolve il problema.
  3. Apri un browser e vai all'URL di destinazione tradizionale dell'annuncio.

Il metodo forCustomFormatAd accetta un OnCustomClickListener. Se passi un oggetto listener, l'SDK richiama il metodo onCustomClick e non esegue ulteriori azioni. Se passi un valore null come listener, tuttavia, l'SDK torna agli URL del link diretto e/o di destinazione registrati con l'annuncio.

I listener 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. Di seguito è riportato un esempio che registra semplicemente il clic:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/6499/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, "/6499/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

All'inizio potrebbe sembrare strano che esistano listener di clic personalizzati. Dopotutto, l'app ha appena comunicato all'SDK che è avvenuto un clic. Perché l'SDK dovrebbe tornare indietro 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. Ad esempio, può eseguire il ping automatico degli URL di monitoraggio di terze parti impostati per la creatività e gestire altre attività dietro le quinte, senza alcun codice aggiuntivo.