Desarrollo de adaptadores de mediación de redes de publicidad

Nota: El uso que hagas del SDK de anuncios de Google para dispositivos móviles en relación con los Servicios de Mediación se rige por las Condiciones del Servicio de Mediación.

Esta guía está diseñada para redes de publicidad en las que se intenta compilar un adaptador de mediación. Si eres editor, consulta las instrucciones sobre mediación para editores.

Un adaptador de red de publicidad es la capa de comunicación entre tu red de publicidad y la mediación de los anuncios móviles de Google.

El adaptador es responsable de implementar MediationBannerAdapter para admitir anuncios de banner y MediationInterstitialAdapter para admitir anuncios intersticiales. También debe invocar las devoluciones de llamada en MediationBannerListener y MediationInterstitialListener en los momentos apropiados para notificar estos eventos a la mediación de los anuncios de Google para dispositivos móviles, que también se pueden reenviar al desarrollador.

Red de publicidad de muestra

En esta guía, se muestra cómo compilar un adaptador para una red de publicidad de muestra. La red de publicidad de muestra contiene las siguientes clases que representan las clases que ofrecen la mayoría de las redes de publicidad:

class SampleAdView {
    public SampleAdView(Context context);
    public void setSize(SampleAdSize size);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void destroy();
}

class SampleAdSize {
    public SampleAdSize(int width, int height);
    public int getWidth();
    public int getHeight();
}

class SampleAdRequest {
    public SampleAdRequest();
    public void setKeywords(Set<String> keywords);
    public void setTestMode(boolean useTesting);
}

class SampleAdListener {
    public void onAdFetchSucceeded();
    public void onAdFetchFailed(SampleErrorCode code);
    public void onAdFullScreen();
    public void onAdClosed();
}

enum SampleErrorCode {
    UNKNOWN,
    BAD_REQUEST,
    NETWORK_ERROR,
    NO_INVENTORY
}

class SampleInterstitial {
    public SampleInterstitial(Context context);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void show();
    public void destroy();
}

Consulta la implementación completa del SDK para obtener más información sobre estas clases.

Cómo implementar un adaptador de banner

Para implementar un adaptador que admita anuncios de banner, crea una clase que implemente MediationBannerAdapter.

public class SampleAdapter implements MediationBannerAdapter {
    @Override
    public void requestBannerAd(
            Context context,
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View getBannerView() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

Antes de profundizar en la implementación de MediationBannerAdapter, analicemos los parámetros del servidor, los elementos adicionales de mediación y la manera en que estos valores se pasan al adaptador.

Parámetros del servidor

Es probable que tu red de publicidad necesite identificadores para poder identificar a un editor. Para la red de publicidad de muestra, por ejemplo, solo se necesita una unidad de anuncios. Estos parámetros obligatorios se te proporcionan en el paquete serverParameters dentro de requestBannerAd(). Durante el desarrollo, puedes suponer que el paquete ya se propagará con las claves que necesitas:

private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

@Override
public void requestBannerAd(
        Context context,
        MediationBannerListener listener,
        Bundle serverParameters,
        AdSize adSize,
        MediationAdRequest mediationAdRequest,
        Bundle mediationExtras) {
    String adUnit = serverParameters.getString(SAMPLE_AD_UNIT_KEY);
    ...
}

AdMob te enviará un cuestionario en el que se te preguntará qué parámetros de servidor necesitas de un publicador para solicitar y publicar anuncios. AdMob utilizará esa entrada para configurar tu red en la IU de AdMob. La siguiente captura de pantalla muestra que APID es obligatorio para Millennial Media y que ID de app es obligatorio para InMobi.

AdMob usará esta información para propagar el paquete serverParameters cuando crees una instancia de tu adaptador.

Consulta este artículo para obtener más información sobre la forma en que los editores configurarán las redes de publicidad de mediación.

Parámetros de segmentación adicionales

El objeto MediationAdRequest contiene información común sobre la segmentación que puedes usar para segmentar anuncios, como los siguientes:

• getKeywords()
• isTesting()
• taggedForChildDirectedTreatment()

Elementos de mediación adicionales

Si tu red de publicidad admite información de segmentación que MediationAdRequest no proporciona, los desarrolladores de apps pueden pasar un paquete de mediationExtras específicamente a tu red. La mediación proporciona un ejemplo de cómo pasar elementos adicionales de mediación.

Para que a los desarrolladores les resulte más fácil pasar esta información de forma opcional, puedes proporcionar una clase de compilador de paquetes en tu adaptador. Supongamos que tu red permite pasar un valor de ingresos. Puedes agregar una clase de compilador en tu adaptador que establezca los ingresos:

public static final class BundleBuilder {
    private int income;

    public BundleBuilder setIncome(int income) {
        this.income = income;
        return this;
    }

    public Bundle build() {
        Bundle bundle = new Bundle();
        bundle.putInt("income", income);
        return bundle;
    }
}

Esta clase proporciona una API limpia a fin de que el desarrollador genere un paquete para tu red:

Bundle sampleAdapterBundle =
        new SampleAdapter.BundleBuilder().setIncome(100000).build();

Nota: MediationExtras será nulo si el desarrollador no proporciona elementos adicionales para tu red.

requestBannerAd()

Ahora que ya presentamos los parámetros de servidor y los elementos de mediación adicionales, podemos usarlos para compilar un MediationBannerAdapter.

Se llama inmediatamente al método requestBannerAd() después de que se crea una instancia del adaptador. Aquí es donde debes crear tu vista de anuncio y realizar una solicitud de anuncio de banner.

Una implementación de requestBannerAd() para la red de publicidad de muestra se ve de la siguiente manera:

public class SampleAdMobAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";
    private SampleAdView sampleAdView;

    @Override
    public void requestBannerAd(
            Context context, // May be an application context.
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleAdView = new SampleAdView(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleAdView.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleAdView.setSize(
                new SampleAdSize(adSize.getWidth(),adSize.getHeight()));

        sampleAdView.setAdListener(
                new SampleBannerEventForwarder(listener, this));

        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleAdView.fetchAd(request);
    }
}

No asumas que el parámetro de contexto es de tipo Activity. Según la implementación del editor, es posible que la mediación de los anuncios de Google para dispositivos móviles reenvíe un contexto de la aplicación a tu adaptador. Si el adaptador no puede controlar un contexto de aplicación, se recomienda invocar a onAdFailedToLoad() con el código de error AdRequest.ERROR_CODE_INVALID_REQUEST.

Devoluciones de llamada de MediationBannerListener

Debes guardar el MediationBannerListener que se te proporcionó en requestBannerAd() para que puedas reenviar eventos de anuncios a la mediación de los anuncios de Google para dispositivos móviles. Cada devolución de llamada se debe invocar en el momento apropiado del ciclo de vida del anuncio:

Método	Cuándo llamar
onAdLoaded()	La solicitud del banner se realizó correctamente.
onAdFailedToLoad()	Se produjo un error en la solicitud del banner.
onAdClicked()	Se hizo clic en el banner.
onAdOpened()	El banner está renderizando una vista de pantalla completa.
onAdClosed()	El usuario regresa a la app después de hacer clic en un banner.
onAdLeftApplication()	El banner hace que el usuario abandone la app.

El adaptador de red de publicidad de muestra crea una clase llamada SampleBannerEventForwarder para controlar el reenvío de eventos:

public class SampleBannerEventForwarder extends SampleAdListener {
    private MediationBannerListener mediationListener;
    private SampleAdapter adapter;

    public SampleBannerEventForwarder(
            MediationBannerListener listener, SampleAdapter adapter) {
        this.mediationListener = listener;
        this.adapter = adapter;
    }

    @Override
    public void onAdFetchSucceeded() {
        mediationListener.onAdLoaded(adapter);
    }

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

    @Override
    public void onAdFullScreen() {
        mediationListener.onAdClicked(adapter);
        mediationListener.onAdOpened(adapter);
        mediationListener.onAdLeftApplication(adapter);
    }

    @Override
    public void onAdClosed() {
        mediationListener.onAdClosed(adapter);
    }
}

Observa cómo el adaptador de red de publicidad de muestra envió onAdClicked, onAdOpened y onAdLeftApplication en la misma devolución de llamada. Aunque es posible que las devoluciones de llamada de tu red no coincidan con exactitud con las devoluciones de llamada que requiere Google Mobile Ads, es responsabilidad del adaptador proporcionar una asignación razonable.

getBannerView

Una vez que llames a MediationBannerListener.onAdLoaded(), la mediación llamará a getBannerView() para mostrar la vista del banner de tu red de publicidad en la pantalla. Simplemente muestra la vista del banner que creaste en requestBannerAd():

@Override
public View getBannerView() {
    return sampleAdView;
}

Eventos del ciclo de vida de la actividad

La mediación notificará al adaptador los eventos de actividad onPause() y onResume() si el desarrollador de la app lo notifica a la mediación. Haz todas las pausas y reanudaciones que sean necesarias en el banner:

@Override
public void onPause() {
}

@Override
public void onResume() {
}

La red de publicidad de muestra no incluye una llamada de pausa ni de reanudación, por lo que proporciona una implementación vacía.

La mediación hará todo lo posible para llamar a onDestroy() cuando el adaptador esté por destruirse. Realiza cualquier limpieza necesaria aquí:

@Override
public void onDestroy() {
    if (sampleAdView != null) {
        sampleAdView.destroy();
    }
}

Banners inteligentes

El SDK de anuncios de Google para dispositivos móviles admite el tamaño de anuncios de banners inteligentes, que es el ancho completo y la altura variable, según el tamaño del dispositivo.

Para obtener con precisión el tamaño del anuncio de un banner inteligente, el adaptador debe usar adSize.getWidthInPixels(context) para obtener el ancho y adSize.getHeightInPixels(context) en lugar de adSize.getHeight() para obtener la altura. Luego, debe dividirse por la densidad del dispositivo:

int widthInPixels = adSize.getWidthInPixels(context);
int heightInPixels = adSize.getHeightInPixels(context);
DisplayMetrics displayMetrics = Resources.getSystem().getDisplayMetrics();
int widthInDp = Math.round(widthInPixels / displayMetrics.density);
int heightInDp = Math.round(heightInPixels / displayMetrics.density);

Luego, puedes usar widthInDp y heightInDp como tamaño cuando realizas una solicitud de anuncio.

Nota: No uses adSize.getWidth() ni adSize.getHeight() para obtener el tamaño del anuncio. Los banners inteligentes se representan internamente con una constante de tamaño especial, por lo que adSize.getWidth() y adSize.getHeight() muestran valores negativos.

Listo. Ahora dispones de un adaptador de mediación que funciona para banners. A modo de referencia, puedes encontrar una implementación completa del SampleAdapter aquí.

Cómo implementar un adaptador intersticial

La implementación del adaptador para anuncios intersticiales es similar a la de anuncios de banner. Para implementar un adaptador que sea compatible con anuncios intersticiales, crea una clase que implemente MediationInterstitialAdapter:

public class SampleAdapter implements MediationInterstitialAdapter {
    @Override
    public void requestInterstitialAd(
            Context context,
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View showInterstitial() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

Si tu adaptador también admite banners, puedes usar la misma clase de adaptador para implementar ambas interfaces.

Familiarízate ahora con los parámetros del servidor y los elementos de mediación adicionales antes de continuar con la implementación de un MediationInterstitialAdapter.

Parámetros de servidor (anuncios intersticiales)

Consulta la sección Parámetros de servidor de banners.

Parámetros de segmentación adicionales (anuncios intersticiales)

Consulta la sección Parámetros de segmentación adicionales de banners.

Elementos de mediación adicionales (anuncios intersticiales)

Consulta la sección Elementos de mediación adicionales de banners.

requestInterstitialAd

Se llama inmediatamente al método requestInterstitialAd() después de que se crea una instancia del adaptador. Aquí es donde debes crear tu anuncio intersticial y realizar una solicitud intersticial.

Una implementación de requestInterstitialAd() para la red de publicidad de muestra se vería de la siguiente manera:

public class SampleAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

    private SampleInterstitial sampleInterstitial;

    @Override
    public void requestInterstitialAd(
            Context context, // May be an application context.
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleInterstitial = new SampleInterstitial(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleInterstitial.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleInterstitial.setAdListener(
                new SampleInterstitialEventForwarder(listener, this));

        // Make an ad request.
        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleInterstitial.fetchAd(request);
    }
}

No des por sentado que el parámetro de contexto es del tipo Activity. La mediación de los anuncios de Google para dispositivos móviles reenvía el contexto que pasó el desarrollador de la app, y es posible que se pase un contexto de aplicación. Si el adaptador no puede controlar un contexto de aplicación, se recomienda invocar a onAdFailedToLoad con el código de error AdRequest.ERROR_CODE_INVALID_REQUEST.

Devoluciones de llamada de MediationIntersticListener

Debes guardar el MediationInterstitialListener que se te proporcionó en requestInterstitialAd para que puedas reenviar eventos de anuncios a la mediación de los anuncios de Google para dispositivos móviles. Cada devolución de llamada se debe invocar en el momento apropiado del ciclo de vida del anuncio:

Método	Cuándo llamar
onAdLoaded	La solicitud intersticial se realizó correctamente.
onAdFailedToLoad	Falló la solicitud intersticial.
onAdOpened	Se muestra el intersticial.
onAdClosed	Se cierra el intersticial.
onAdLeftApplication	El intersticial hace que el usuario abandone la app.

showInterstitial

Una vez que llames a MediationInterstitialListener.onAdLoaded(), debes esperar para mostrar el anuncio intersticial hasta que se llame a showInterstitial(). El desarrollador de la app decide cuándo mostrar el anuncio intersticial. Esto puede ser varios minutos después de la solicitud.

La implementación en showInterstitial() es bastante sencilla. Solo debes mostrar tu objeto intersticial:

@Override
public void showInterstitial() {
    sampleInterstitial.show();
}

Eventos del ciclo de vida de una actividad (anuncios intersticiales)

Consulta la sección Eventos del ciclo de vida de una actividad de banner.

Después de implementar eventos de ciclo de vida de la actividad, tu adaptador de mediación estará listo para manejar anuncios intersticiales. A modo de referencia, puedes encontrar una implementación completa del SampleAdapter aquí.

Preguntas frecuentes

¿Qué debo hacer si mi adaptador solo admite anuncios intersticiales o de banner, pero no ambos?

Si el adaptador solo admite banners, debes implementar la interfaz de MediationBannerAdapter. Si tu adaptador solo admite anuncios intersticiales, deberás implementar la interfaz de MediationInterstitialAdapter.