Eventos nativos personalizados

Esta guía está dirigida a aquellos editores que quieran utilizar la mediación de AdMob para cargar y mostrar anuncios nativos de una red que no sea una de las redes publicitarias compatibles de AdMob. Consulta la sección Eventos personalizados para obtener información sobre cómo usar la mediación de AdMob para cargar y mostrar anuncios de banner o intersticiales. Los eventos personalizados son clases de adaptadores de mediación que pueden solicitar anuncios a otra red. Si añades el nombre de una de estas clases a la configuración de mediación de un bloque de anuncios, el SDK de anuncios de Google para móviles podrá crear una instancia y usarla para mostrar anuncios. Las clases de eventos nativos personalizados deben poder hacer lo siguiente:

  • Solicitar anuncios nativos a una red con mediación.
  • Reenviar eventos desde el SDK de la red con mediación al SDK de anuncios de Google para móviles.
  • Utilizar una clase UnifiedNativeAdMapper para asignar anuncios nativos con mediación a la interfaz de anuncios nativos de AdMob.

A continuación se explica cada una de esas tareas. También puedes consultar el código fuente completo de un proyecto de evento personalizado de muestra en nuestro repositorio de GitHub.

Requisitos

Para implementar un evento personalizado de AdMob, primero debes integrar el SDK de anuncios para móviles en tu proyecto. Además, es recomendable que leas primero la documentación sobre cómo hacer una AdRequest y cómo funciona la mediación.

SDK de ejemplo

Los fragmentos de código utilizados en esta guía se han extraído de nuestro proyecto de evento personalizado de muestra, que incluye un SDK de ejemplo. Este simulacro de SDK se usa en nuestro ejemplo de cómo crear un evento personalizado que medie con el SDK de otra red publicitaria.

El SDK de ejemplo incluye clases similares a las de los SDK de producción de redes publicitarias. Contiene objetos de solicitud como SampleNativeAdRequest, cargadores de anuncios como SampleNativeAdLoader, así como otras clases, constantes e interfaces que se utilizan para simular el SDK de una red real. No obstante, los anuncios que produce son ficticios y no se genera ningún tráfico de red adicional.

Solicitar un anuncio nativo

Método requestNativeAd()

Las clases de eventos personalizados deben implementar la interfaz CustomEventNative, que incluye un método empleado por el SDK de anuncios de Google para móviles para solicitar anuncios nativos desde eventos personalizados:

Java

    void requestNativeAd(Context context,
            CustomEventNativeListener listener,
            String serverParameter,
            NativeMediationAdRequest mediationAdRequest,
            Bundle customEventExtras);
    

Kotlin

    override fun requestNativeAd(context: Context,
            listener: CustomEventNativeListener,
            serverParameter: String,
            mediationAdRequest: NativeMediationAdRequest,
            customEventExtras: Bundle?)
    

Al hacer una llamada a este método, el evento personalizado debe realizar una solicitud asíncrona de un anuncio nativo a la red con mediación. Los siguientes parámetros del método requestNativeAd() contienen información que el evento personalizado puede usar para hacer la solicitud:

  • serverParameter: al añadir un evento personalizado a la configuración de mediación de un bloque de anuncios, los editores pueden introducir un valor de cadena para que se transfiera con cada solicitud. Este parámetro contiene dicho valor (normalmente, otro ID de bloque de anuncios, emitido por la red con mediación).
  • mediationAdRequest: un objeto NativeMediationAdRequest que contiene propiedades específicas de una sola solicitud, como los formatos nativos que se solicitan. NativeMediationAdRequest es una subclase de MediationAdRequest, por lo que también incluye propiedades sobre los datos de segmentación que proporcionan los editores al hacer solicitudes.
  • customEventExtras: una clase Bundle que contiene información extra relacionada con la solicitud y que proporciona el editor. Al crear una solicitud de anuncio, los editores pueden usar el método addNetworkExtrasBundle() para incluir información relacionada con adaptadores de mediación y eventos personalizados concretos. En este parámetro se encuentra la información adicional que ha incluido el editor sobre una determinada clase de evento personalizado.

Aparte de los que contienen la información de la solicitud, hay otros dos parámetros:

  • context: un objeto Context que se puede usar si el evento personalizado lo requiere.
  • listener: un objeto CustomEventNativeListener que el evento personalizado debe utilizar para reenviar eventos.

El objeto listener es especialmente importante, ya que se utiliza para informar de los eventos al SDK de anuncios de Google para móviles. En la sección Reenviar eventos al SDK de anuncios para móviles de esta guía se explica cómo hacerlo.

Aquí tienes un fragmento de código de nuestro ejemplo de proyecto de evento personalizado, en el que se muestra un método requestNativeAd() implementado:

SampleCustomEvent (fragmento)

Java

    @Override
    public void requestNativeAd(Context context,
                                CustomEventNativeListener customEventNativeListener,
                                String serverParameter,
                                NativeMediationAdRequest nativeMediationAdRequest,
                                Bundle extras) {
        // Create one of the Sample SDK's ad loaders from which to request ads.
        SampleNativeAdLoader loader = new SampleNativeAdLoader(context);
        loader.setAdUnit(serverParameter);

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

            // If your network does not support any of the following options, please make sure
            // that it is documented in your adapter's documentation.
            request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages());
            switch (options.getImageOrientation()) {
                case NativeAdOptions.ORIENTATION_LANDSCAPE:
                    request.setPreferredImageOrientation(
                            SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE);
                    break;
                case NativeAdOptions.ORIENTATION_PORTRAIT:
                    request.setPreferredImageOrientation(
                            SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT);
                    break;
                case NativeAdOptions.ORIENTATION_ANY:
                default:
                    request.setPreferredImageOrientation(
                            SampleNativeAdRequest.IMAGE_ORIENTATION_ANY);
            }
        }

        if (!nativeMediationAdRequest.isUnifiedNativeAdRequested()) {
            Log.e(TAG, "Failed to load ad. Request must be for unified native ads.");
            customEventNativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST);
            return;
        }

        loader.setNativeAdListener(
                new SampleCustomNativeEventForwarder(customEventNativeListener, options));

        // Begin a request.
        loader.fetchAd(request);
    }
    

Kotlin

    override fun requestNativeAd(context: Context,
                                 customEventNativeListener: CustomEventNativeListener,
                                 serverParameter: String,
                                 nativeMediationAdRequest: NativeMediationAdRequest,
                                 extras: Bundle) {
        // Create one of the Sample SDK's ad loaders from which to request ads.
        val loader = SampleNativeAdLoader(context)
        loader.setAdUnit(serverParameter)

        // Create a native request to give to the SampleNativeAdLoader.
        val request = SampleNativeAdRequest()
        val options = nativeMediationAdRequest.nativeAdOptions
        if (options != null) {
            // If the NativeAdOptions' shouldReturnUrlsForImageAssets is true, the adapter should
            // send just the URLs for the images.
            request.shouldDownloadImages = !options.shouldReturnUrlsForImageAssets()

            // If your network does not support any of the following options, please make sure
            // that it is documented in your adapter's documentation.
            request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages())
            when (options.imageOrientation) {
                NativeAdOptions.ORIENTATION_LANDSCAPE -> request.setPreferredImageOrientation(
                        SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE)
                NativeAdOptions.ORIENTATION_PORTRAIT -> request.setPreferredImageOrientation(
                        SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT)
                NativeAdOptions.ORIENTATION_ANY -> request.setPreferredImageOrientation(
                        SampleNativeAdRequest.IMAGE_ORIENTATION_ANY)
                else -> request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_ANY)
            }
        }

        if (!nativeMediationAdRequest.isUnifiedNativeAdRequested) {
            Log.e(TAG, "Failed to load ad. Request must be for unified native ads.")
            customEventNativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST)
            return
        }

        loader.setNativeAdListener(
                SampleCustomNativeEventForwarder(customEventNativeListener, options))

        // Begin a request.
        loader.fetchAd(request)
    }

Se trata de un evento personalizado de muestra que media con una red publicitaria ficticia a través del simulacro del SDK de ejemplo. Dicho evento personalizado utiliza la información proporcionada por los parámetros del método requestNativeAd() para desarrollar una SampleNativeAdRequest (una clase que proporciona el SDK de ejemplo) y usarla para solicitar un anuncio al objeto SampleNativeAdLoader del SDK de ejemplo. También crea un objeto SampleCustomEventNativeForwarder para gestionar el reenvío de los eventos al SDK de anuncios de Google para móviles.

NativeAdOptions

Al solicitar anuncios nativos, los editores utilizan un objeto NativeAdOptions para especificar las preferencias de dicha solicitud, como la forma en la que se deben devolver los recursos de imagen. Tu evento personalizado debe examinar y respetar dichas preferencias. Los eventos personalizados pueden obtener el objeto NativeAdOptions de una solicitud mediante el método getNativeAdOptions() que proporciona el objeto NativeMediationAdRequest:

Java

    NativeAdOptions options = mediationAdRequest.getNativeAdOptions();
    

Kotlin

    val options = mediationAdRequest.nativeAdOptions
    

Después de obtener el objeto NativeAdOptions, los eventos personalizados pueden leer sus propiedades y actuar en consecuencia. Por ejemplo, si el valor shouldReturnUrlsForImageAssets del objeto NativeAdOptions es "false" (que es el valor predeterminado), el evento personalizado debe devolver recursos de imagen, no solo URLs. En este caso, si el SDK con mediación solo proporciona las URL de las imágenes, el evento personalizado deberá usarlas para descargar los archivos de imagen y poner sus datos a disposición de los editores en los anuncios nativos asignados.

Reenviar eventos al SDK Mobile Ads

Cuando un evento personalizado intenta cargar un anuncio nativo desde su red con mediación, el SDK puede devolver correctamente un anuncio nativo, pero también puede hacerlo con un error o, sencillamente, informar de que no hay anuncios disponibles. De igual forma, si un usuario toca un anuncio, el SDK con mediación podría abrir una superposición o salir de la aplicación para abrir un navegador externo. Es importante que el SDK de anuncios de Google para móviles esté al tanto de estos eventos, de forma que proporcione un objeto CustomEventNativeListener como parámetro del método requestNativeAd().

Una de las funciones de los eventos personalizados consiste en detectar los eventos del SDK con mediación y asociarlos a las retrollamadas adecuadas del objeto CustomEventNativeListener. El evento personalizado debe estar informado de las siguientes retrollamadas de CustomEventNativeListener:

  • onAdLoaded(): se debe llamar a este método cuando un evento personalizado carga correctamente un anuncio nativo. Este método usa un objeto UnifiedNativeAdMapper, que asigna el anuncio nativo del SDK de tu red publicitaria a un objeto que el SDK de anuncios de Google para móviles entiende. En la sección Asignar anuncios nativos se explica cómo crear un objeto UnifiedNativeAdMapper.
  • onAdFailedToLoad(): cuando el evento personalizado intenta cargar un anuncio nativo y no lo consigue, debe utilizar este método para informar del error. Se debe usar un solo parámetro de número entero, al que se le debe asignar una de las constantes de error:

  • onAdLeftApplication(): se debe invocar este método cuando el SDK con mediación provoque que el usuario salga de la aplicación del editor (normalmente, para abrir un navegador externo).

  • onAdOpened(): se debe invocar este método si, en respuesta a un toque del usuario, el anuncio nativo abre una superposición o actividad independiente que cubre la interfaz. Entre estos elementos se incluyen los navegadores externos, en cuyo caso tu evento personalizado debería llamar al método onAdOpened justo antes de al método onAdLeftApplication.

  • onAdClosed(): se debe invocar este método si se cierra una superposición o una actividad independiente que cubra la interfaz, lo que significa que la aplicación que contiene el anuncio nativo vuelve a tener el control.

El listener también ofrece métodos para informar de los clics y las impresiones de los eventos personalizados que optan por hacer un seguimiento de dichos eventos por sí mismos. Para obtener más información sobre este tema, consulta la sección Anular los valores predeterminados de gestión de clics y registro de impresiones. De los siguientes métodos, uno se usa para informar de un clic al SDK de anuncios de Google para móviles y, el otro, para informar de una impresión:

  • onAdClicked(): se debe llamar a este método cuando un usuario haga clic en un anuncio nativo.
  • onAdImpression(): del mismo modo, se debe llamar a este método cuando el SDK con mediación registre una impresión de anuncio.

Hay varias formas de asegurarse de que los eventos se reenvían correctamente, pero una de las más sencillas consiste en crear una clase específica para que se haga cargo del reenvío. Aquí puedes ver un ejemplo, extraído de nuestro proyecto de ejemplo de evento personalizado:

SampleCustomNativeEventForwarder

Java

    public class SampleCustomNativeEventForwarder extends SampleNativeAdListener {
        private CustomEventNativeListener nativeListener;
        private NativeAdOptions nativeAdOptions;

        public SampleCustomNativeEventForwarder(
                CustomEventNativeListener listener, NativeAdOptions options) {
            this.nativeListener = listener;
            this.nativeAdOptions = options;
        }

        @Override
        public void onNativeAdFetched(SampleNativeAd ad) {
            SampleUnifiedNativeAdMapper mapper =
                    new SampleUnifiedNativeAdMapper(ad, nativeAdOptions);
            nativeListener.onAdLoaded(mapper);
        }

        @Override
        public void onAdFetchFailed(SampleErrorCode errorCode) {
            switch (errorCode) {
                case UNKNOWN:
                    nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INTERNAL_ERROR);
                    break;
                case BAD_REQUEST:
                    nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST);
                    break;
                case NETWORK_ERROR:
                    nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NETWORK_ERROR);
                    break;
                case NO_INVENTORY:
                    nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NO_FILL);
                    break;
            }
        }
    }
    

Kotlin

    class SampleCustomNativeEventForwarder(
            private val nativeListener: CustomEventNativeListener,
            private val nativeAdOptions: NativeAdOptions) : SampleNativeAdListener() {

        fun onNativeAdFetched(ad: SampleNativeAd) {
            val mapper = SampleUnifiedNativeAdMapper(ad, nativeAdOptions)
            nativeListener.onAdLoaded(mapper)
        }

        fun onAdFetchFailed(errorCode: SampleErrorCode) {
            when (errorCode) {
                UNKNOWN -> nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INTERNAL_ERROR)
                BAD_REQUEST -> nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST)
                NETWORK_ERROR -> nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NETWORK_ERROR)
                NO_INVENTORY -> nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NO_FILL)
            }
        }
    }
    

Fíjate en que la clase implementa la interfaz SampleNativeAdListener del SDK de ejemplo. En la sección SampleCustomEvent (fragmento), se proporcionó una instancia de esta clase de reenviador al objeto SampleNativeAdLoader en su método setNativeAdListener():

Java

    loader.setNativeAdListener(new SampleCustomNativeEventForwarder(customEventNativeListener, options));
    

Kotlin

    loader.setNativeAdListener(SampleCustomNativeEventForwarder(customEventNativeListener, options))
    

De este modo, nos aseguramos de que el SDK de ejemplo llama a los métodos del listener (onNativeAdFetched(), onAdFetchFailed(), etc.) del objeto SampleCustomNativeEventForwarder cuando debe informar de un evento. A continuación, el reenviador llama al método correspondiente en el objeto CustomEventNativeListener del SDK de anuncios de Google para móviles y, por último, reenvía el evento. Dicho de otra forma, el SDK de anuncios de Google para móviles recibe información del reenviador, que, a su vez, recibe información del SDK con mediación.

El método onAdFetchFailed() anterior es un buen ejemplo de este proceso. Cuando el SDK de ejemplo no puede cargar un anuncio, llama al método onAdFetchFailed() del reenviador y le proporciona un código de error. El reenviador examina el código de error y llama al método onAdFailedToLoad() del objeto CustomEventNativeListener con uno de los códigos de error que utiliza el SDK de anuncios de Google para móviles. De esta manera, el evento del SDK de ejemplo se transforma en un evento del SDK de anuncios de Google para móviles.

Asignación de anuncios nativos

Cada SDK tiene su propio formato de anuncios nativos. Por ejemplo, es posible que uno devuelva objetos que contengan un campo "title", mientras que otros podrían tener un campo "headline". Además, los métodos utilizados para hacer el seguimiento de las impresiones y procesar los clics pueden variar de un SDK a otro. La clase UnifiedNativeAdMapper debe paliar esas diferencias y adaptar un objeto de anuncio nativo del SDK con mediación, de forma que coincida con la interfaz que espera el SDK de anuncios Google para móviles. Los eventos personalizados deben ampliar esta clase para crear sus propios asignadores para el SDK con mediación.

A continuación, te mostramos un ejemplo de asignador de anuncios, extraído de nuestro ejemplo de proyecto de evento personalizado:

SampleUnifiedNativeAdMapper

Java

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

Kotlin

    class SampleUnifiedNativeAdMapper(private val sampleAd: SampleNativeAd) : UnifiedNativeAdMapper() {

        init {
            headline = sampleAd.headline
            body = sampleAd.body
            callToAction = sampleAd.callToAction
            starRating = sampleAd.starRating
            store = sampleAd.storeName
            icon = SampleNativeMappedImage(sampleAd.icon, sampleAd.iconUri,
                    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE)
            advertiser = sampleAd.advertiser

            val imagesList = ArrayList<NativeAd.Image>()
            imagesList.add(SampleNativeMappedImage(sampleAd.image, sampleAd.imageUri,
                    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE))
            images = imagesList

            if (sampleAd.price != null) {
                val formatter = NumberFormat.getCurrencyInstance()
                val priceString = formatter.format(sampleAd.price)
                price = priceString
            }

            val extras = Bundle()
            extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, sampleAd.degreeOfAwesomeness)
            this.extras = extras

            overrideClickHandling = false
            overrideImpressionRecording = false

            adChoicesContent = sampleAd.informationIcon
        }

        override fun recordImpression() {
            sampleAd.recordImpression()
        }

        override fun handleClick(view: View?) {
            sampleAd.handleClick(view)
        }
    }

Echemos un vistazo al método del agente constructor y a parte de la función que desempeña:

Incluir referencias a objetos de anuncio nativo con mediación

El constructor acepta los parámetros SampleNativeAd y NativeAdOptions. SampleNativeAd es la clase de anuncio nativo que utiliza el SDK de ejemplo para sus anuncios nativos. Para poder transmitir los eventos de clics e impresiones, el asignador necesita una referencia al anuncio con mediación. NativeAdOptions contiene las preferencias del editor referentes al anuncio nativo. Ambos parámetros se almacenan como variables locales.

Configurar propiedades de recursos asignados

El agente constructor usa el objeto SampleNativeAd para rellenar los recursos de la clase UnifiedNativeAdMapper. Por ejemplo, este código obtiene los datos del precio del anuncio con mediación y los utiliza para definir el precio del asignador:

Java

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

Kotlin

    if (sampleAd.price != null) {
        val formatter = NumberFormat.getCurrencyInstance()
        val priceString = formatter.format(sampleAd.price)
        price = priceString
    }
    

En este caso, el anuncio con mediación almacena el precio como un valor double, mientras que AdMob usa un valor String en ese mismo recurso. El asignador es responsable de gestionar esas conversiones.

Asignar recursos de imagen

La asignación de recursos de imagen es más complicada que la de otros tipos de datos más sencillos, como double o String. Las imágenes se pueden descargar automáticamente o se pueden devolver simplemente como valores de URL. Sus escalas de píxeles a ppp también pueden variar. Para ayudar a los desarrolladores de eventos personalizados a gestionar estos detalles, el SDK de anuncios de Google para móviles proporciona la clase NativeAd.Image. De la misma manera que los desarrolladores necesitan crear una subclase de UnifiedNativeAdMapper para asignar un anuncio nativo con mediación, también deben crear una subclase de NativeAd.Image que les permita asignar sus recursos de imagen.

Este es el código correspondiente a la clase SampleNativeMappedImage del evento personalizado:

Java

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

Kotlin

    class SampleNativeMappedImage(private val drawable: Drawable,
                                  private val imageUri: Uri,
                                  private val scale: Double) : NativeAd.Image() {

        override fun getDrawable(): Drawable {
            return drawable
        }

        override fun getUri(): Uri {
            return imageUri
        }

        override fun getScale(): Double {
            return scale
        }
    }
    

En esta línea, el objeto SampleUnifiedNativeAdMapper usa su clase de imagen asignada para configurar el recurso de imagen del icono del asignador:

Java

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

Kotlin

    icon = SampleNativeMappedImage(sampleAd.appIcon, sampleAd.appIconUri,
            SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE)
    

Añadir campos al paquete de recursos adicionales

Algunos SDK con mediación pueden proporcionar recursos adicionales, aparte de los que se encuentran en el formato de anuncios nativos de AdMob. La clase UnifiedNativeAdMapper incluye un método setExtras() que se utiliza para transferir esos recursos a los editores. El objeto SampleUnifiedNativeAdMapper lo utiliza en el recurso "degree of awesomeness" (grado de genialidad) del SDK de ejemplo:

Java

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

Kotlin

    val extras = Bundle()
    extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, sampleAd.degreeOfAwesomeness)
    this.extras = extras
    

Los editores pueden obtener los datos mediante el método getExtras() de la clase UnifiedNativeAd.

Gestión de anuncios

Tu evento personalizado debe proporcionar un icono de Gestión de anuncios a través del método setAdChoicesContent() de la clase UnifiedNativeAdMapper.

A continuación, puedes ver un fragmento del objeto SampleUnifiedNativeAdMapper en el que se muestra cómo proporcionar dicho icono:

Java

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

Kotlin

    init {
        ...
        adChoicesContent = sampleAd.informationIcon
    }
    

Eventos de impresión y clic

Tanto el SDK de anuncios de Google para móviles como el SDK con mediación deben saber cuándo se produce una impresión o un clic, pero solo un SDK tiene que hacer el seguimiento de dichos eventos. Los eventos personalizados pueden adoptar dos enfoques diferentes, en función de si el SDK con mediación puede hacer el seguimiento de las impresiones y los clics por su cuenta o no.

Gestionar clics e impresiones con handleClick y recordImpression

Si el SDK con mediación no puede hacer el seguimiento de las impresiones y los clics por su cuenta, pero sí proporciona métodos para registrarlos, el SDK de anuncios de Google para móviles puede hacer un seguimiento de esos eventos y notificárselo al adaptador. La clase UnifiedNativeAdMapper incluye dos métodos, recordImpression() y handleClick(), que los eventos personalizados pueden implementar para llamar al método correspondiente del objeto de anuncio nativo con mediación.

A continuación te enseñamos qué hace SampleUnifiedNativeAdMapper para gestionar esta situación:

Java

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

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

Kotlin

    override fun recordImpression() {
        sampleAd.recordImpression()
    }

    override fun handleClick(view: View) {
        sampleAd.handleClick(view)
    }
    

Dado que el objeto SampleUnifiedNativeAdMapper contiene una referencia al objeto de anuncio nativo del SDK de ejemplo, para informar de un clic o una impresión, el asignador solo tiene que llamar al método correspondiente de ese objeto. Ten en cuenta que el método handleClick() solo tiene un parámetro, que es el objeto View correspondiente al recurso de anuncio nativo que recibió el clic.

Anular los valores predeterminados de gestión de clics y registro de impresiones

Es posible que algunos SDK con mediación prefieran hacer un seguimiento de los clics e impresiones por su cuenta. En ese caso, debes anular el seguimiento predeterminado de las impresiones y los clics. Para ello, haz las siguientes dos llamadas en el constructor de tu clase UnifiedNativeAdMapper:

Java

    setOverrideClickHandling(true);
    setOverrideImpressionRecording(true);
    

Kotlin

    setOverrideClickHandling(true)
    setOverrideImpressionRecording(true)
    

Tal como se indica en la sección Reenviar eventos al SDK de anuncios para móviles, los eventos personalizados que hagan un seguimiento de los clics y las impresiones por su cuenta deben informar de esos eventos al SDK de anuncios de Google para móviles a través de los métodos onAdClicked() y onAdImpression().

Asimismo, debes anular el método trackViews() y usarlo para transferir la vista del anuncio nativo al SDK con mediación para que se pueda hacer el seguimiento. El SDK de ejemplo de nuestro proyecto de muestra de un evento personalizado (del que se han extraído los fragmentos de código de esta guía) no utiliza esta opción, pero si lo hiciera, el código del evento personalizado tendría este aspecto:

Java

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

Kotlin


    override fun trackViews(containerView: View?,
            clickableAssetViews: Map<String, View>?,
            nonClickableAssetViews: Map<String, View>?) {
        sampleAd.setNativeAdViewForTracking(containerView)
    }
    

Si el SDK con mediación puede hacer un seguimiento de recursos concretos, también puede buscar en clickableAssetViews para comprobar en qué vistas se puede hacer clic. A esta asociación se le asigna un nombre de recurso en la clase UnifiedNativeAdAssetNames.

La clase UnifiedNativeAdMapper también ofrece un método untrackView() que tus eventos personalizados pueden anular con el propósito contrario (es decir, para eliminar cualquier referencia a la vista y desvincularla del objeto de anuncio nativo).

Usar eventos personalizados

Para usar un evento personalizado, debes añadirlo a la configuración de mediación de un bloque de anuncios. Esta operación se lleva a cabo en la interfaz de usuario de AdMob. En la sección Añadir un evento personalizado, encontrarás instrucciones detalladas para editar la configuración de mediación de un bloque de anuncios.

Cuando añadas el evento personalizado a la configuración de mediación de un bloque de anuncios, deberás facilitar tres datos:

  • Class Name: el nombre de la clase del evento personalizado, con el nombre completo del paquete.
  • Label: la etiqueta que quieres que use la interfaz de AdMob para representar el evento personalizado cuando muestre las fuentes de mediación del bloque de anuncios. Solo la verás tú, ya que aparece únicamente en la interfaz de usuario de AdMob.
  • Parameter: es un valor de cadena que se transfiere al evento personalizado cada vez que se emite una solicitud a este bloque de anuncios. Normalmente, este valor se define como un ID de bloque de anuncios de la red con mediación.

En esta captura de pantalla puedes ver un ejemplo de introducción de un evento personalizado:

Eso es todo. Ya tienes todo lo que necesitas para crear tus propios eventos personalizados de Android para AdMob.