Eventos personalizados de anuncios nativos

Requisitos previos

Completa la configuración de eventos personalizados.

Cómo solicitar un anuncio nativo

Cuando se alcanza la línea de pedido del evento personalizado en la cadena de mediación en cascada, Se llama al método loadNativeAd() en el nombre de clase que proporcionaste cuando creación de una campaña evento. En este caso, ese método está en SampleCustomEvent, que luego llama el método loadNativeAd() en SampleNativeCustomEventLoader

Para solicitar un anuncio nativo, crea o modifica una clase que extienda Adapter a implementa loadNativeAd(). Si ya existe una clase que extiende Adapter, implementa loadNativeAd() allí. Además, crea una nueva clase para implementar UnifiedNativeAdMapper

En nuestro ejemplo de evento personalizado, SampleCustomEvent extiende la clase Adapter y, luego, delega a SampleNativeCustomEventLoader

package com.google.ads.mediation.sample.customevent;

import com.google.android.gms.ads.mediation.Adapter;
import com.google.android.gms.ads.mediation.MediationAdConfiguration;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;

import com.google.android.gms.ads.mediation.MediationNativeAdCallback;
...
public class SampleCustomEvent extends Adapter {
  private SampleNativeCustomEventLoader nativeLoader;

  @Override
  public void loadNativeAd(
      @NonNull MediationNativeAdConfiguration adConfiguration,
      @NonNull MediationAdLoadCallback<UnifiedNativeAdMapper, MediationNativeAdCallback> callback) {
    nativeLoader = new SampleNativeCustomEventLoader(adConfiguration, callback);
    nativeLoader.loadAd();
  }
}

SampleNativeCustomEventLoader es responsable de las siguientes tareas:

• Se está cargando el anuncio nativo.

• Cómo implementar la clase UnifiedNativeAdMapper

• Recibir e informar devoluciones de llamadas de eventos de anuncios al SDK de anuncios de Google para dispositivos móviles

El parámetro opcional definido en la IU de Ad Manager es incluidas en la configuración del anuncio. Se puede acceder al parámetro adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) Este parámetro suele ser un identificador de unidades de anuncios cuando se crea una instancia de un objeto de anuncio.

package com.google.ads.mediation.sample.customevent;

import com.google.android.gms.ads.mediation.Adapter;
import com.google.android.gms.ads.mediation.MediationNativeAdConfiguration;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
import com.google.android.gms.ads.mediation.MediationNativeAdCallback;
...

public class SampleNativeCustomEventLoader extends SampleNativeAdListener {
  /** Configuration for requesting the native ad from the third-party network. */
  private final MediationNativeAdConfiguration mediationNativeAdConfiguration;

  /** Callback that fires on loading success or failure. */
  private final MediationAdLoadCallback<UnifiedNativeAdMapper, MediationNativeAdCallback>
      mediationAdLoadCallback;

  /** Callback for native ad events. */
  private MediationNativeAdCallback nativeAdCallback;

  /** Constructor */
  public SampleNativeCustomEventLoader(
      @NonNull MediationNativeAdConfiguration mediationNativeAdConfiguration,
      @NonNull MediationAdLoadCallback<MediationNativeAd, MediationNativeAdCallback>
              mediationAdLoadCallback) {
    this.mediationNativeAdConfiguration = mediationNativeAdConfiguration;
    this.mediationAdLoadCallback = mediationAdLoadCallback;
  }

  /** Loads the native ad from the third-party ad network. */
  public void loadAd() {
    // Create one of the Sample SDK's ad loaders to request ads.
    Log.i("NativeCustomEvent", "Begin loading native ad.");
    SampleNativeAdLoader loader =
        new SampleNativeAdLoader(mediationNativeAdConfiguration.getContext());

    // All custom events have a server parameter named "parameter" that returns
    // back the parameter entered into the UI when defining the custom event.
    String serverParameter = mediationNativeAdConfiguration
        .getServerParameters()
        .getString(MediationConfiguration
        .CUSTOM_EVENT_SERVER_PARAMETER_FIELD);
    Log.d("NativeCustomEvent", "Received server parameter.");

    loader.setAdUnit(serverParameter);

    // Create a native request to give to the SampleNativeAdLoader.
    SampleNativeAdRequest request = new SampleNativeAdRequest();
    NativeAdOptions options = mediationNativeAdConfiguration.getNativeAdOptions();
    if (options != null) {
      // If the NativeAdOptions' shouldReturnUrlsForImageAssets is true, the adapter should
      // send just the URLs for the images.
      request.setShouldDownloadImages(!options.shouldReturnUrlsForImageAssets());

      request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages());
      switch (options.getMediaAspectRatio()) {
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE);
          break;
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_PORTRAIT:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT);
          break;
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_SQUARE:
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_ANY:
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_UNKNOWN:
        default:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_ANY);
      }
    }

    loader.setNativeAdListener(this);

    // Begin a request.
    Log.i("NativeCustomEvent", "Start fetching native ad.");
    loader.fetchAd(request);
  }
}

Según si el anuncio se recupera correctamente o encuentra un error, puedes llamaría cualquiera onSuccess() o onFailure() Se llama a onSuccess() pasando una instancia de la clase que implementa MediationNativeAd

Por lo general, estos métodos se implementan dentro de devoluciones de llamada del o SDK de terceros que implemente tu adaptador. Para este ejemplo, el SDK de muestra tiene un SampleAdListener con devoluciones de llamada relevantes:

@Override
public void onNativeAdFetched(SampleNativeAd ad) {
  SampleUnifiedNativeAdMapper mapper = new SampleUnifiedNativeAdMapper(ad);
  mediationNativeAdCallback = mediationAdLoadCallback.onSuccess(mapper);
}

@Override
public void onAdFetchFailed(SampleErrorCode errorCode) {
  mediationAdLoadCallback.onFailure(SampleCustomEventError.createSampleSdkError(errorCode));
}

Cómo asignar anuncios nativos

Los diferentes SDK tienen sus propios formatos únicos para los anuncios nativos. Uno podría regresar objetos que contienen un "título" campo, por ejemplo, mientras que otro podría tener "título". Además, los métodos usados para hacer un seguimiento de las impresiones y procesar de clics varíen de un SDK a otro.

El UnifiedNativeAdMapper es responsable de conciliar estas diferencias y adaptar el objeto de anuncio nativo de un SDK mediado para que coincida con la interfaz que espera el el SDK de anuncios de Google para dispositivos móviles. Los eventos personalizados deberían extender esta clase para crear sus propios mappers específicos para su SDK mediado. Este es un ejemplo de un asignador de anuncios nuestro proyecto de evento personalizado de ejemplo:

package com.google.ads.mediation.sample.customevent;

import com.google.android.gms.ads.mediation.UnifiedNativeAdMapper;
import com.google.android.gms.ads.nativead.NativeAd;
...

public class SampleUnifiedNativeAdMapper extends UnifiedNativeAdMapper {

  private final SampleNativeAd sampleAd;

  public SampleUnifiedNativeAdMapper(SampleNativeAd ad) {
    sampleAd = ad;
    setHeadline(sampleAd.getHeadline());
    setBody(sampleAd.getBody());
    setCallToAction(sampleAd.getCallToAction());
    setStarRating(sampleAd.getStarRating());
    setStore(sampleAd.getStoreName());
    setIcon(
        new SampleNativeMappedImage(
            ad.getIcon(), ad.getIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
    setAdvertiser(ad.getAdvertiser());

    List<NativeAd.Image> imagesList = new ArrayList<NativeAd.Image>();
    imagesList.add(new SampleNativeMappedImage(ad.getImage(), ad.getImageUri(),
        SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
    setImages(imagesList);

    if (sampleAd.getPrice() != null) {
      NumberFormat formatter = NumberFormat.getCurrencyInstance();
      String priceString = formatter.format(sampleAd.getPrice());
      setPrice(priceString);
    }

    Bundle extras = new Bundle();
    extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
    this.setExtras(extras);

    setOverrideClickHandling(false);
    setOverrideImpressionRecording(false);

    setAdChoicesContent(sampleAd.getInformationIcon());
  }

  @Override
  public void recordImpression() {
    sampleAd.recordImpression();
  }

  @Override
  public void handleClick(View view) {
    sampleAd.handleClick(view);
  }

  // The Sample SDK doesn't do its own impression/click tracking, instead relies on its
  // publishers calling the recordImpression and handleClick methods on its native ad object. So
  // there's no need to pass a reference to the View being used to display the native ad. If
  // your mediated network does need a reference to the view, the following method can be used
  // to provide one.

  @Override
  public void trackViews(View containerView, Map<String, View> clickableAssetViews,
      Map<String, View> nonClickableAssetViews) {
    super.trackViews(containerView, clickableAssetViews, nonClickableAssetViews);
    // If your ad network SDK does its own impression tracking, here is where you can track the
    // top level native ad view and its individual asset views.
  }

  @Override
  public void untrackView(View view) {
    super.untrackView(view);
    // Here you would remove any trackers from the View added in trackView.
  }
}

Ahora, analizaremos con más detalle el código del constructor.

Contener una referencia al objeto de anuncio nativo mediado

El constructor acepta el parámetro SampleNativeAd, la clase de anuncio nativo que se usa. en el SDK de muestra para sus anuncios nativos. El asignador necesita una referencia al anuncio mediado para que pueda pasar eventos de clics e impresiones. SampleNativeAd es se almacenan como una variable local.

Cómo establecer propiedades de elementos asignados

El constructor usa el objeto SampleNativeAd para propagar los recursos en el UnifiedNativeAdMapper

Este fragmento obtiene los datos de precios del anuncio mediado y los usa para establecer la Precio:

if (sampleAd.getPrice() != null) {
    NumberFormat formatter = NumberFormat.getCurrencyInstance();
    String priceString = formatter.format(sampleAd.getPrice());
    setPrice(priceString);
}

En este ejemplo, el anuncio mediado almacena el precio como un double, mientras que Ad Manager usa un String para el mismo recurso. El asignador es responsable de administrar este tipo de conversiones.

Cómo asignar recursos de imagen

Asignar recursos de imagen es más complicado que asignar tipos de datos, como double o String. Es posible que las imágenes se descarguen automáticamente se muestran como valores de URL. Sus escalas de píxeles a DPI también pueden variar.

Para ayudarte a administrar estos detalles, el SDK de anuncios de Google para dispositivos móviles proporciona la Clase NativeAd.Image. De la misma manera en que se necesita crear una subclase de UnifiedNativeAdMapper para asignar un anuncio nativo mediado, también debes crear un subclase de NativeAd.Image cuando se asignan recursos de imagen.

Este es un ejemplo de la clase SampleNativeMappedImage del evento personalizado:

public class SampleNativeMappedImage extends NativeAd.Image {

  private Drawable drawable;
  private Uri imageUri;
  private double scale;

  public SampleNativeMappedImage(Drawable drawable, Uri imageUri, double scale) {
    this.drawable = drawable;
    this.imageUri = imageUri;
    this.scale = scale;
  }

  @Override
  public Drawable getDrawable() {
    return drawable;
  }

  @Override
  public Uri getUri() {
    return imageUri;
  }

  @Override
  public double getScale() {
    return scale;
  }
}

SampleNativeAdMapper usa la clase de imagen asignada en esta línea para establecer la recurso de imagen de ícono del asignador:

setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(),
    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));

Cómo agregar campos al paquete de extras

Algunos SDK mediados proporcionan elementos adicionales aparte de los que se encuentran en el Es el formato del anuncio nativo de Ad Manager. El UnifiedNativeAdMapper incluye un método setExtras() que se usa para pasar estos elementos a publicadores. El SampleNativeAdMapper lo usa para los SDK de muestra. "grado de genialidad" recurso:

Bundle extras = new Bundle();
extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
this.setExtras(extras);

Los publicadores pueden recuperar los datos con la clase NativeAd. getExtras() .

AdChoices

Tu evento personalizado es responsable de proporcionar un ícono de AdChoices mediante el setAdChoicesContent() en UnifiedNativeAdMapper Este es un fragmento de SampleNativeAdMapper que muestra cómo proporcionar el ícono de AdChoices:

public SampleNativeAdMapper(SampleNativeAd ad) {
    ...
    setAdChoicesContent(sampleAd.getInformationIcon());
}

Eventos de impresiones y clics

Tanto el SDK de anuncios de Google para dispositivos móviles como el SDK mediado deben saber cuándo un se produce una impresión o un clic, pero solo un SDK debe hacer un seguimiento de estos eventos. Hay hay dos enfoques diferentes que los eventos personalizados pueden usar, dependiendo de si SDK mediado admite el seguimiento de impresiones y clics por su cuenta.

Cómo hacer un seguimiento de los clics y las impresiones con el SDK de anuncios de Google para dispositivos móviles

Si el SDK mediado no realiza su propio seguimiento de impresiones y clics, pero proporciona métodos para registrar impresiones y clics, el SDK de anuncios de Google hacer un seguimiento de estos eventos y notificar al adaptador. El La clase UnifiedNativeAdMapper incluye dos métodos: recordImpression() y handleClick() los eventos personalizados pueden implementarse para llamar al método correspondiente en la instancia objeto de anuncio nativo:

@Override
public void recordImpression() {
  sampleAd.recordImpression();
}

@Override
public void handleClick(View view) {
  sampleAd.handleClick(view);
}

Debido a que SampleNativeAdMapper contiene una referencia al SDK nativo del SDK de muestra objeto de anuncio, puede llamar al método apropiado en ese objeto para informar un clic o impresión. Ten en cuenta que el método handleClick() toma un Parámetro único: el objeto View que corresponde al recurso del anuncio nativo que que recibieron el clic.

Haz un seguimiento de los clics y las impresiones con el SDK mediado

Es posible que algunos SDKs mediados prefieran hacer un seguimiento de los clics y las impresiones por su cuenta. En en ese caso, deberías anular el seguimiento predeterminado de clics e impresiones Realiza las dos llamadas siguientes en el constructor de tu UnifiedNativeAdMapper:

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

Los eventos personalizados que anulen el seguimiento de clics y de impresiones deben informar los eventos onAdClicked() y onAdImpression() a Google para dispositivos móviles SDK de Google Ads.

Para hacer un seguimiento de las impresiones y los clics, es probable que el SDK mediado necesite acceder a la vistas para habilitar el seguimiento. El evento personalizado debe anular el trackViews() y úsalo para pasar la vista del anuncio nativo a los SDK de seguimiento. El SDK de muestra de nuestro proyecto de evento personalizado (del cual los fragmentos de código de esta guía) no usa este enfoque; pero si Así lo hizo, el código del evento personalizado se vería así:

@Override
public void trackViews(View containerView,
    Map<String, View> clickableAssetViews,
    Map<String, View> nonClickableAssetViews) {
  sampleAd.setNativeAdViewForTracking(containerView);
}

Si el SDK mediado admite el seguimiento de elementos individuales, puede buscar dentro clickableAssetViews para ver en qué vistas se puede hacer clic. Este mapa es clave con un nombre de recurso en NativeAdAssetNames. El UnifiedNativeAdMapper Ofrece un método untrackView() correspondiente que los eventos personalizados pueden anular. para liberar cualquier referencia a la vista y desvincularla del anuncio nativo .

Reenvía eventos de mediación al SDK de anuncios de Google para dispositivos móviles

Puedes encontrar todas las devoluciones de llamada que admite la mediación en la documentos de MediationNativeAdCallback.

Es importante que tu evento personalizado reenvíe tantas de estas devoluciones de llamada como sea posible posible, de modo que tu app reciba estos eventos equivalentes de la API de Google SDK de anuncios para dispositivos móviles. Este es un ejemplo del uso de devoluciones de llamada:

Esto completa la implementación de eventos personalizados para los anuncios nativos. El ejemplo completo está disponible en GitHub: