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 degli annunci nativi definendo elenchi personalizzati di asset. Questi si chiamano annunci nativi personalizzati formati e può essere utilizzata annunci prenotati. In questo modo, i publisher possono trasmettere dati strutturati arbitrari alle proprie app. Questi annunci sono rappresentati NativeCustomFormatAd .

Carica formati di annunci nativi personalizzati

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

Creare un AdLoader

Come per gli annunci nativi, i formati di 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 l'elemento AdLoader per richiedere servizi formati di annunci nativi. Nel metodo vengono passati tre parametri:

  • L'ID del formato di annuncio nativo personalizzato che AdLoader deve richiedere. Ciascuna formato di annuncio nativo personalizzato ha associato un ID. Questo parametro indica il formato che l'app vuole che AdLoader richieda.
  • Un OnCustomFormatAdLoadedListener essere richiamato quando un annuncio viene caricato correttamente.
  • Un'etichetta facoltativa OnCustomClickListener da richiamare quando l'utente tocca o fa clic sull'annuncio. Per ulteriori informazioni consulta la sezione "Gestione di clic e impressioni" di seguito.

Perché una singola unità pubblicitaria può essere impostata per pubblicare più di una creatività formato forCustomFormatAd, può essere chiamato più volte con ID formato in modo da preparare il caricatore degli annunci per più di una possibile formato di annuncio nativo personalizzato.

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 di annuncio nativo personalizzato viene visualizzato accanto al nome. Facendo clic su uno dei di i nomi ti consente di visualizzare una schermata dei dettagli che mostra le informazioni sul campi:

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

Formati di annunci nativi personalizzati per la Rete Display

I formati di annunci nativi personalizzati sono diversi da quelli definiti dal sistema in hanno la possibilità di definire il proprio elenco di risorse che creare un annuncio. Di conseguenza, la procedura per mostrarne uno è diverso da quello definito dal sistema. in vari 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 un corso di visualizzazione degli annunci dedicato come NativeAdView da utilizzare con NativeCustomFormatAd. Sei libero di utilizzare qualsiasi layout che in base alla tua esperienza utente.
  3. Poiché non esiste un corso ViewGroup dedicato, non è necessario registrarsi qualsiasi visualizzazione utilizzata per mostrare gli asset dell'annuncio. Ciò consente di risparmiare di codice durante la visualizzazione dell'annuncio, ma richiede anche un piccolo intervento in più gestire i clic in un secondo momento.

Di seguito è riportato 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 Regolamento sui servizi digitali (DSA), Gli annunci basati su prenotazione pubblicati nello Spazio economico europeo (SEE) richiedono Icona Scegli Tu! e un link alla pagina Su questo annuncio di Google. Quando implementi annunci nativi personalizzati, è tua responsabilità eseguire il rendering Icona Scegli Tu!. Ti consigliamo di eseguire il rendering e impostare il clic ascoltatore dell'icona Scegli Tu! durante il rendering degli asset annuncio principali.

L'esempio seguente presuppone che tu abbia definito un elemento <ImageView /> in la gerarchia di visualizzazioni per contenere 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>

Gli esempi riportati di seguito mostrano l'icona Scegli Tu! configurare il comportamento del 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 i formati degli annunci nativi personalizzati

Quando crei un formato personalizzato, puoi scegliere di rendere il formato 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. alla visualizzazione dei contenuti multimediali. Se l'annuncio non include contenuti video, crea piani alternativi per mostrarlo senza video.

L'esempio riportato di seguito verifica se l'annuncio presenta contenuti video e mostra un'immagine al posto del video se non è disponibile:

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

Consulta MediaContent per ulteriori informazioni personalizzare l'esperienza video di un annuncio nativo personalizzato.

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

Impressioni e clic per i formati degli annunci nativi personalizzati

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

Registra impressioni

Per registrare un'impressione per un annuncio in formato personalizzato, chiama il metodo recordImpression sul metodo 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 richiesta.

Clic nei report

Per segnalare all'SDK che si è verificato un clic su una visualizzazione di asset, richiama il metodo performClick sul metodo NativeCustomFormatAd corrispondente e trasmettilo il nome dell'asset 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 vista associata a il tuo annuncio. Se avessi un altro campo chiamato "Sottotitolo" che doveva essere ma che l'utente non ha fatto clic o toccato, la tua app non deve richiama performClick per la visualizzazione dell'asset.

Rispondere alle azioni di clic personalizzate

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

  1. Richiama OnCustomClickListener da AdLoader, se ne è stato fornito uno.
  2. Per ciascuno degli URL dei link diretti dell'annuncio, prova a individuare un resolver di contenuti e avvia la prima che si risolve.
  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 nullo come listener, l'SDK torna al link diretto e/o agli URL di destinazione registrati con annuncio.

I listener di clic personalizzati consentono alla tua app di decidere l'azione migliore da intraprendere risposta a un clic, ad esempio l'aggiornamento dell'interfaccia utente, l'avvio di una nuova attività o semplicemente registrando il clic. Ecco un esempio che registra semplicemente un clic effettuato luogo:

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

Inizialmente potrebbe sembrare strano l'esistenza di listener di clic personalizzati. Dopotutto, l'app ha appena comunicato all'SDK che si è verificato un clic, pertanto perché l'SDK dovrebbe e segnalarlo all'app?

Questo flusso di informazioni è utile per vari 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.