Utilizzare 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 di annunci nativi definendo elenchi personalizzati di asset. Questi sono chiamati formati di annunci nativi personalizzati, e possono essere utilizzati con gli annunci riservati. In questo modo, i publisher possono trasmettere dati strutturati arbitrari alle loro app. Questi annunci sono rappresentati dall' NativeCustomFormatAd oggetto.

Caricare formati di annunci nativi personalizzati

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

Caricare un annuncio nativo personalizzato

Per caricare un annuncio nativo personalizzato:

  1. Includi il tipo NativeAdType.CUSTOM_NATIVE come tipo di annuncio in NativeAdRequest.

  2. Imposta l'ID formato dell'annuncio nativo personalizzato.

Kotlin

val adRequest =
  NativeAdRequest.Builder("AD_UNIT_ID", listOf(NativeAdType.CUSTOM_NATIVE))
    .setCustomFormatIds(listOf("CUSTOM_NATIVE_FORMAT_ID"))
    .build()

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
  adRequest,
  object : NativeAdLoaderCallback {
    override fun onCustomNativeAdLoaded(customNativeAd: CustomNativeAd) {
      // TODO: Store the custom native ad.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {}
  },
)
CustomNativeSnippets.kt

Java

NativeAdRequest adRequest =
    new NativeAdRequest.Builder("AD_UNIT_ID", List.of(NativeAd.NativeAdType.CUSTOM_NATIVE))
        .setCustomFormatIds(Arrays.asList("CUSTOM_NATIVE_FORMAT_ID"))
        .build();

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
    adRequest,
    new NativeAdLoaderCallback() {
      @Override
      public void onCustomNativeAdLoaded(@NonNull CustomNativeAd customNativeAd) {
        // TODO: Store the custom native ad.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {}
    });
CustomNativeSnippets.java

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 dell'annuncio nativo personalizzato viene visualizzato accanto al relativo nome. Se fai clic su uno dei nomi, viene visualizzata una schermata dei dettagli con informazioni sui campi del formato:

Da qui è possibile aggiungere, modificare e rimuovere i singoli campi. Prendi nota del nome di ogni asset. Il nome è la chiave utilizzata per recuperare i dati di ogni asset quando viene visualizzato il formato dell'annuncio nativo personalizzato.

Visualizzare formati di annunci nativi personalizzati

I formati di annunci nativi personalizzati differiscono 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 visualizzarne uno differisce dai formati definiti dal sistema in alcuni modi:

  1. Gli asset di testo e immagine sono disponibili tramite i getter getText() e getImage() che accettano il nome del campo come parametro.
  2. Poiché non esiste una classe ViewGroup dedicata da registrare con Google, devi registrare manualmente impressioni e clic.
  3. Un annuncio nativo personalizzato ha contenuti multimediali null se non contiene un asset video.

Questo esempio mostra come visualizzare un CustomNativeAd:

Kotlin

private fun displayCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  customNativeAdBinding.headline.text = customNativeAd.getText("Headline")
  customNativeAdBinding.caption.text = customNativeAd.getText("Caption")

  // If the main asset is an image, render it with an ImageView.
  val imageView = ImageView(context)
  imageView.adjustViewBounds = true
  imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
  imageView.setOnClickListener { customNativeAd.performClick("MainImage") }
  customNativeAdBinding.mediaPlaceholder.addView(imageView)

  // Render the ad choices icon.
  renderAdChoices(customNativeAd)

  // Record an impression.
  customNativeAd.recordImpression()
}

CustomNativeSnippets.kt

Java

private void displayCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  if (customNativeAdBinding != null) {
    customNativeAdBinding.headline.setText(customNativeAd.getText("Headline"));
    customNativeAdBinding.caption.setText(customNativeAd.getText("Caption"));

    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    imageView.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            customNativeAd.performClick("MainImage");
          }
        });
    customNativeAdBinding.mediaPlaceholder.addView(imageView);

    // Render the ad choices icon.
    renderAdChoices(customNativeAd);

    // Record an impression.
    customNativeAd.recordImpression();
  }
}

CustomNativeSnippets.java

Video nativo per formati di annunci nativi personalizzati

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

Nell'implementazione dell'app, puoi utilizzare CustomNativeAd.getMediaContent() per ottenere i contenuti multimediali. Poi chiama setMediaContent() per impostare i contenuti multimediali nel pannello multimediale. Se l'annuncio ha contenuti multimediali null, pianifica alternative per mostrare l'annuncio senza un video.

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

Kotlin

private fun displayVideoCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Check whether the custom native ad has video content.
  val mediaContent = customNativeAd.mediaContent
  if (mediaContent != null && mediaContent.hasVideoContent) {
    // Render the media content in a MediaView.
    val mediaView = MediaView(context)
    mediaView.mediaContent = mediaContent
    customNativeAdBinding.mediaPlaceholder.addView(mediaView)
  } else {
    // Fall back to other assets defined on your custom native ad.
    val imageView = ImageView(context)
    imageView.adjustViewBounds = true
    imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
    customNativeAdBinding.mediaPlaceholder.addView(imageView)
  }

  // Record an impression.
  customNativeAd.recordImpression()
}

CustomNativeSnippets.kt

Java

private void displayVideoCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Check whether the custom native ad has video content.
  MediaContent mediaContent = customNativeAd.getMediaContent();
  if (mediaContent != null && mediaContent.getHasVideoContent()) {
    // Render the media content in a MediaView.
    MediaView mediaView = new MediaView(context);
    mediaView.setMediaContent(mediaContent);
    customNativeAdBinding.mediaPlaceholder.addView(mediaView);
  } else {
    // Fall back to other assets defined on your custom native ad.
    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    customNativeAdBinding.mediaPlaceholder.addView(imageView);
  }

  // Record an impression.
  customNativeAd.recordImpression();
}

CustomNativeSnippets.java

Per ulteriori informazioni su come personalizzare l'esperienza video di un annuncio nativo personalizzato, consulta Annunci video.

Eseguire il rendering dell'icona Scegli Tu!

Nell'ambito del supporto al Regolamento sui servizi digitali (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.

L'esempio seguente presuppone che tu abbia definito un elemento <ImageView /> nella gerarchia di oggetti View 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 seguenti eseguono il rendering dell'icona Scegli Tu! e configurano il comportamento di clic appropriato.

Kotlin

private fun renderAdChoices(customNativeAd: CustomNativeAd) {
  // Render the AdChoices image.
  val adChoiceAsset = customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
  if (adChoiceAsset != null) {
    customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.drawable)
    customNativeAdBinding.adchoices.visibility = View.VISIBLE
    customNativeAdBinding.adchoices.setOnClickListener {
      // Handle click. See the next section for more details.
      customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
    }
  } else {
    customNativeAdBinding.adchoices.visibility = View.GONE
  }
}

CustomNativeSnippets.kt

Java

private void renderAdChoices(CustomNativeAd customNativeAd) {
  // Render the AdChoices image.
  Image adChoiceAsset =
      customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
  if (adChoiceAsset != null) {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.getDrawable());
      customNativeAdBinding.adchoices.setVisibility(View.VISIBLE);
      customNativeAdBinding.adchoices.setOnClickListener(
          new View.OnClickListener() {
            @Override
            public void onClick(View v) {
              // Handle click.
              customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
            }
          });
    }
  } else {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setVisibility(View.GONE);
    }
  }
}

CustomNativeSnippets.java

Registrare le impressioni e segnalare i clic

La tua app è responsabile della registrazione delle impressioni e della segnalazione degli eventi di clic a GMA Next-Gen SDK.

Registrare le impressioni

Per registrare un'impressione per un annuncio nativo personalizzato, chiama il metodo recordImpression() dell'annuncio:

Kotlin

// Record an impression.
customNativeAd.recordImpression()
CustomNativeSnippets.kt

Java

// Record an impression.
customNativeAd.recordImpression();
CustomNativeSnippets.java

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.

Segnalare i clic

Per segnalare all'SDK che si è verificato un clic su una visualizzazione di asset, chiama il metodo performClick() dell'annuncio. Fornisci il nome dell'asset su cui è stato fatto clic utilizzando la stessa stringa definita nell'interfaccia utente di Ad Manager.

Kotlin

imageView.setOnClickListener { customNativeAd.performClick("MainImage") }
CustomNativeSnippets.kt

Java

imageView.setOnClickListener(
    new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        customNativeAd.performClick("MainImage");
      }
    });
CustomNativeSnippets.java

Tieni presente che non devi chiamare questo metodo per ogni visualizzazione associata al tuo annuncio. Se avevi un altro campo chiamato "Didascalia" che doveva essere visualizzato ma non su cui l'utente non doveva fare clic o toccare, la tua app non avrebbe dovuto chiamare performClick per la visualizzazione di quell'asset.

Rispondere alle azioni di clic personalizzate

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

  1. Richiama OnCustomClickListener se ne è stato fornito uno.
  2. Per ogni URL di link diretto dell'annuncio, tenta di individuare un content resolver e avvia il primo che viene risolto.
  3. Apri un browser e vai all'URL di destinazione dell'annuncio.

Per implementare un'azione di clic personalizzata, fornisci un OnCustomClickListener:

Kotlin

customNativeAd.onCustomClickListener =
  object : OnCustomClickListener {
    override fun onCustomClick(assetName: String) {
      // Perform your custom action.
    }
  }
CustomNativeSnippets.kt

Java

customNativeAd.setOnCustomClickListener(
    new OnCustomClickListener() {
      @Override
      public void onCustomClick(@NonNull String assetName) {
        // Perform your custom action.
      }
    });
CustomNativeSnippets.java

All'inizio, potrebbe sembrare strano che esistano listener di clic personalizzati. Dopo tutto, la tua app ha appena comunicato all'SDK che si è verificato un clic, quindi perché l'SDK dovrebbe segnalarlo all'app?

Questo flusso di informazioni è utile per alcuni motivi, ma soprattutto consente all'SDK di mantenere il controllo della risposta al clic. Ad esempio, può eseguire automaticamente il ping degli URL di monitoraggio di terze parti impostati per la creatività e gestire altre attività dietro le quinte, senza codice aggiuntivo.