Formatos de anuncios nativos personalizados

Formatos personalizados del anuncio nativo

Además de los formatos nativos definidos por el sistema, los publicadores de Ad Manager tienen la opción de crear sus propios formatos de anuncios nativos definiendo listas personalizadas de recursos. Estos se denominan formatos de anuncios nativos personalizados y se pueden usar con anuncios reservados. Esto permite a los publicadores pasar datos estructurados arbitrarios a sus apps. Estos anuncios se representan con el objeto NativeCustomFormatAd.

Carga formatos de anuncios nativos personalizados

En esta guía, se explica cómo cargar y mostrar formatos de anuncios nativos personalizados.

Compila un AdLoader

Al igual que los anuncios nativos, los formatos de anuncios nativos personalizados se cargan con la clase 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()

El método forCustomFormatAd configura el AdLoader para solicitar formatos de anuncios nativos personalizados. Se pasan tres parámetros al método:

  • Es el ID del formato de anuncio nativo personalizado que debe solicitar AdLoader. Cada formato de anuncio nativo personalizado tiene un ID asociado. Este parámetro indica qué formato desea que AdLoader solicite tu app.
  • Un OnCustomFormatAdLoadedListener que se invocará cuando se cargue un anuncio correctamente.
  • Un OnCustomClickListener opcional que se invocará cuando el usuario presione o haga clic en el anuncio. Para obtener más información sobre este objeto de escucha, consulta la sección "Cómo controlar las impresiones y los clics" a continuación.

Debido a que se puede configurar una sola unidad de anuncios para publicar más de un formato de creatividad, se puede llamar a forCustomFormatAd varias veces con IDs de formato únicos para preparar el cargador de anuncios para más de un formato de anuncio nativo personalizado posible.

ID del formato de anuncio nativo personalizado

El ID de formato que se usa para identificar un formato de anuncio nativo personalizado se puede encontrar en la IU de Ad Manager, en la sección Nativo del menú desplegable Publicación:

Cada ID de formato de anuncio nativo personalizado aparece junto a su nombre. Si haces clic en uno de los nombres, se abrirá una pantalla de detalles que muestra información sobre los campos del formato:

Desde aquí, se pueden agregar, editar y quitar campos individuales. Anota el Nombre de cada uno de los recursos. El nombre es la clave que se usa para obtener los datos de cada recurso cuando se muestra tu formato de anuncio nativo personalizado.

Cómo mostrar formatos personalizados de anuncios nativos

Los formatos de anuncios nativos personalizados difieren de los definidos por el sistema en que los publicadores tienen la capacidad de definir su propia lista de recursos que conforman un anuncio. Por lo tanto, el proceso para mostrar uno difiere de los formatos definidos por el sistema de varias maneras:

  1. Debido a que la clase NativeCustomFormatAd está diseñada para controlar cualquiera de los formatos de anuncios nativos personalizados que definas en Ad Manager, no tiene "obtentores" nombrados para los recursos. En su lugar, ofrece métodos como getText y getImage que toman el nombre del campo como parámetro.
  2. No hay una clase de vista de anuncio dedicada como NativeAdView para usar con NativeCustomFormatAd. Puedes usar cualquier diseño que tenga sentido para tu experiencia del usuario.
  3. Como no hay una clase ViewGroup dedicada, no necesitas registrar ninguna de las vistas que usas para mostrar los recursos del anuncio. Esto ahorra algunas líneas de código cuando se muestra el anuncio, pero también significa que deberás hacer un poco más de trabajo para controlar los clics más adelante.

Este es un ejemplo de función que muestra 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.
    ...
}

Renderiza el ícono de AdChoices

Como parte de la aplicación de la Ley de Servicios Digitales (DSA), los anuncios de reserva que se publican en el Espacio Económico Europeo (EEE) requieren un ícono de AdChoices y un vínculo a la página Acerca de este anuncio de Google. Cuando implementes anuncios nativos personalizados, serás responsable de renderizar el ícono de AdChoices. Te recomendamos que sigas los pasos para renderizar y configurar el objeto de escucha de clics para el ícono de AdChoices cuando renderices los recursos de anuncios principales.

En el siguiente ejemplo, se supone que definiste un elemento <ImageView /> en tu jerarquía de vistas para contener el logotipo de AdChoices.

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

En los siguientes ejemplos, se renderiza el ícono de AdChoices y se configura el comportamiento de clic adecuado.

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 para formatos de anuncios nativos personalizados

Cuando creas un formato personalizado, tienes la opción de que sea apto para videos.

En la implementación de tu app, puedes usar NativeCustomFormatAd.getMediaContent() para obtener el contenido multimedia. Luego, llama a setMediaContent() para configurar el contenido multimedia en tu vista multimedia. Si el anuncio no tiene contenido de video, crea planes alternativos para mostrarlo sin video.

En el siguiente ejemplo, se verifica si el anuncio tiene contenido de video y se muestra una imagen en su lugar si no hay un video disponible:

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 para obtener más información sobre cómo personalizar la experiencia de video de un anuncio nativo personalizado.

Descarga el ejemplo de renderización personalizada de Ad Manager para ver un ejemplo en funcionamiento de un video nativo en acción.

Impresiones y clics de formatos personalizados de anuncios nativos

Con los formatos de anuncios nativos personalizados, tu app es responsable de registrar las impresiones y de informar los eventos de clics al SDK de anuncios de Google para dispositivos móviles.

Registra las impresiones

Para registrar una impresión de un anuncio de formato personalizado, llama al método recordImpression en el NativeCustomFormatAd correspondiente:

myCustomFormatAd.recordImpression();

Si tu app llama accidentalmente al método dos veces para el mismo anuncio, el SDK prevente automáticamente que se registre una impresión duplicada para una sola solicitud.

Cómo informar clics

Para informar al SDK que se produjo un clic en una vista de activo, llama al método performClick en el NativeCustomFormatAd correspondiente y pasa el nombre del activo en el que se hizo clic. Por ejemplo, si tuvieras un activo en tu formato personalizado llamado "MainImage" y quisieras informar un clic en el ImageView que corresponde a ese activo, tu código se vería de la siguiente manera:

myCustomFormatAd.performClick("MainImage");

Ten en cuenta que no es necesario que llames a este método para cada vista asociada con tu anuncio. Si tuvieras otro campo llamado "Subtítulo" que se mostrara, pero el usuario no hiciera clic en él, tu app no tendría que llamar a performClick para la vista de ese recurso.

Cómo responder a acciones de clic personalizadas

Cuando se realiza un clic en un anuncio de formato personalizado, hay tres respuestas posibles del SDK, que se intentan en este orden:

  1. Invoca el OnCustomClickListener de AdLoader, si se proporcionó uno.
  2. Para cada una de las URLs de vínculo directo del anuncio, intenta encontrar un solucionador de contenido y, luego, inicia el primero que se resuelva.
  3. Abre un navegador y navega a la URL de destino tradicional del anuncio.

El método forCustomFormatAd acepta un OnCustomClickListener. Si pasas un objeto de objeto de escucha, el SDK invoca su método onCustomClick y no realiza ninguna otra acción. Sin embargo, si pasas un valor nulo como el objeto de escucha, el SDK recurre al vínculo directo o a las URLs de destino registradas con el anuncio.

Los objetos de escucha de clics personalizados permiten que tu app decida la mejor acción que se debe realizar en respuesta a un clic, ya sea actualizar la IU, iniciar una actividad nueva o simplemente registrar el clic. Este es un ejemplo que simplemente registra que se produjo 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()

Al principio, puede parecer extraño que existan objetos de escucha de clics personalizados. Después de todo, tu app acaba de decirle al SDK que se produjo un clic, así que ¿por qué el SDK debería dar la vuelta y informarlo a la app?

Este flujo de información es útil por varios motivos, pero lo más importante es que permite que el SDK mantenga el control de la respuesta al clic. Por ejemplo, puede enviar pings automáticamente a las URLs de seguimiento de terceros que se configuraron para la creatividad y controlar otras tareas en segundo plano, sin ningún código adicional.