Desarrollo de adaptadores de ofertas

Esta guía está destinada a las redes de publicidad que buscan crear un adaptador de ofertas para participar en las ofertas en tiempo real (RTB) dentro de la mediación de Google. Si eres un editor, consulta las instrucciones sobre mediación de editores.

Un adaptador de ofertas es la parte del cliente de la integración. El adaptador permite que tu SDK de red de publicidad se comunique con el SDK de anuncios de Google para dispositivos móviles a fin de cargar anuncios que publique tu ofertante.

Para que las ofertas funcionen correctamente, el adaptador deberá controlar la inicialización, la recopilación de indicadores, la carga de anuncios y la retransmisión de eventos del ciclo de vida de los anuncios. En esta guía, te indicaremos cómo debes implementar tu adaptador para controlar estas operaciones.

Nota: La participación en la licitación también requiere un ofertante que pueda responder las solicitudes de OpenRTB. Las instrucciones para presentar a un ofertante están fuera del alcance de esta guía.

Flujo de trabajo de un adaptador de ofertas

Inicialización

A continuación, se muestra un flujo detallado de todo el ciclo de vida de renderización de solicitudes y respuestas de un adaptador:

El adaptador es responsable de las siguientes partes del flujo de trabajo:

• Pasos 4 a 7: Inicializa el adaptador y vuelve a llamar al SDK de anuncios de Google para dispositivos móviles una vez que se complete la inicialización.

• Pasos 10 a 13: Recopila indicadores del SDK de tu red de publicidad para que se envíen a tu ofertante a fin de participar en una solicitud de RTB y reenvíalos al SDK de anuncios de Google para dispositivos móviles.

• Pasos 18 a 21: Si el ofertante devuelve la oferta ganadora, carga el anuncio según la respuesta de tu ofertante. Una vez cargado, notifica al SDK de anuncios de Google para dispositivos móviles que se cargó el anuncio.

• Paso 23 y versiones posteriores: Mientras se muestra tu anuncio, notifica al SDK de anuncios de Google para dispositivos móviles sobre los eventos de impresiones y clics, así como los demás eventos de anuncios que ocurren durante el ciclo de vida de la presentación de tu anuncio.

Nota: El SDK de anuncios de Google para dispositivos móviles hace un seguimiento independiente de los eventos de impresión, pero también es importante que reenvíes el evento de impresión de tu red de publicidad para que podamos verificar si hay discrepancias.

Cómo implementar el adaptador de ofertas

Si deseas crear un adaptador de ofertas para el SDK de anuncios de Google para dispositivos móviles, debes extender la clase abstracta RtbAdapter. En las siguientes secciones, se explica cada método abstracto en RtbAdapter.

getSDKVersionInfo()

Aquí debes mostrar la versión de tu SDK. Esta versión se pasa a tu ofertante como parte de la solicitud de OpenRTB.

Este método requiere que devuelvas un VersionInfo. En el siguiente ejemplo, se muestra cómo convertir la versión de cadena del SDK en una VersionInfo..

@Override
public VersionInfo getSDKVersionInfo() {
  // Get your SDK's version as a string. E.g. "1.2.3"
  // String versionString = YourSdk.getVersion();
  String splits[] = versionString.split("\\.");
  if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
   }

   String logMessage = String.format("Unexpected SDK version format: %s." +
           "Returning 0.0.0 for SDK version.", sdkVersion);
   Log.w(TAG, logMessage);
   return new VersionInfo(0, 0, 0);
}

getVersionInfo()

Aquí debes mostrar la versión del adaptador. Esta versión se pasa a tu ofertante como parte de la solicitud de OpenRTB.

Los adaptadores de código abierto y de versión de Google usan un esquema de versión de adaptador de 4 dígitos, pero VersionInfo solo permite 3 dígitos. Para solucionar este problema, se recomienda combinar los últimos dos dígitos en la versión del parche, como se muestra a continuación.

@Override
public VersionInfo getVersionInfo() {
  // Get your adapters's version as a string. E.g. "1.2.3.0"
  String versionString = BuildConfig.VERSION_NAME;
  String splits[] = versionString.split("\\.");
  if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    String logMessage = String.format("Unexpected adapter version format: %s." +
                "Returning 0.0.0 for adapter version.", versionString);
    Log.w(TAG, logMessage);
    return new VersionInfo(0, 0, 0);
}

initialize()

Tiempo de espera: 30 segundos

El método initialize() es el primer método al que se llama en el adaptador. Se llama solo una vez por sesión. Este método te proporciona una lista de objetos MediationConfiguration que representan la lista completa de posiciones en esta app que se configuraron para tu red de publicidad. Puedes recorrer esta lista a fin de analizar las credenciales de cada posición y pasar datos relevantes a tu SDK para la inicialización.

Una vez que se inicialice el SDK y esté listo para recibir solicitudes de anuncios, invoca el método onInitializationSucceeded() de InitializationCompleteCallback. Esta devolución de llamada se reenvía a los publicadores de la app para que sepan que pueden comenzar a cargar anuncios.

Nota: Se llama al método initialize() en una instancia desechable de un adaptador. No se llamará a ningún otro método en esta instancia en particular. Si el adaptador necesita guardar el estado como resultado de este método, cualquier estado debe ser estático.

@Override
public void initialize(Context context,
    InitializationCompleteCallback initializationCompleteCallback,
    List<MediationConfiguration> mediationConfigurations) {
  // Initialize your ad network's SDK.
  ...

  // Invoke the InitializationCompleteCallback once initialization completes.
  initializationCompleteCallback.onInitializationSucceeded();
}

collectSignals()

Tiempo de espera: 1 segundo

Cada vez que el publicador solicita un anuncio, se crea una instancia nueva de tu RtbAdapter y se llama al método collectSignals(). Esta instancia de RtbAdapter se usará durante el ciclo de vida de la solicitud de anuncio, la respuesta y la renderización de ese anuncio. El método collectSignals() permite que el adaptador proporcione indicadores del dispositivo que se enviarán a tu ofertante en una solicitud de OpenRTB.

Se llama a collectSignals() en un subproceso en segundo plano. El SDK de anuncios de Google para dispositivos móviles solicita simultáneamente indicadores de todos los adaptadores que participan en las ofertas. Sé respetuoso y limita las llamadas al subproceso de IU durante este período. Cualquier trabajo pesado que tu adaptador o SDK deba realizar para recopilar indicadores debe realizarse en el método initialize() y almacenarse en caché.

Una vez que tengas los indicadores listos, llama a la devolución de llamada onSuccess() con los indicadores codificados.

A continuación, se incluye un ejemplo de implementación:

@Override
public void collectSignals(RtbSignalData rtbSignalData,
                           SignalCallbacks signalCallbacks) {
  String signals = YourSdk.getSignals();
  signalCallbacks.onSuccess(signals);
}

Si el adaptador no puede recopilar indicadores, llama a signalCallbacks.onFailure() con una cadena que explique el error que se produjo.

Nota: La string de indicadores podría representar cualquier objeto y podría estar en cualquier formato, como JSON sin formato, codificado en Base64 o cualquier otra forma de encriptación que elijas. Se recomienda la encriptación de indicadores para garantizar que sean opacas fuera de la red.

Implementa métodos de carga de anuncios

Tiempo de espera: 10 segundos

Si el ofertante muestra la oferta ganadora, el SDK de los anuncios de Google para dispositivos móviles llama a tu adaptador a fin de cargar el anuncio ganador y te pasa los datos que haya mostrado el ofertante y que el SDK necesita para cargar ese anuncio.

El método de carga exacto al que se llama depende del formato del anuncio para el que se realiza esta solicitud:

Formato del anuncio	Método de carga
Banner	loadBannerAd()
Intersticial	loadInterstitialAd()
Recompensado	loadRewardedAd()

Implementa estos métodos para los formatos de anuncios que admite tu adaptador.

Se llama al método de carga en el subproceso de IU, en la misma instancia del adaptador desde el que proporcionaste señales. Este método te proporciona los siguientes parámetros:

• Una MediationAdConfiguration, que contiene los parámetros que tu SDK necesita para cargar el anuncio de la oferta ganadora, como la respuesta a la oferta y las credenciales que el publicador configuró en la IU de AdMob

• Es un objeto MediationAdLoadCallback que se usa para notificar al SDK de anuncios de Google para dispositivos móviles cuando la carga se realiza correctamente o falla.

Una vez que tu SDK cargue el anuncio, llama a mediationAdLoadCallback.onSuccess(). En el evento de que la carga de anuncios falle, llama a mediationAdLoadCallback.onFailure() con una cadena que explique el error que se produjo.

El método mediationAdLoadCallback.onSuccess() requiere que pases un objeto que lo confirme a una de las interfaces "Ad" definidas por el SDK de Google Mobile Ads. Estas interfaces te solicitan que proporciones información sobre el anuncio.

MediationAdConfiguration también tiene un método getWatermark() para mostrar una cadena codificada en base64 que representa una imagen PNG. Esta imagen debe aparecer en mosaico en una superposición transparente en sus anuncios. Comunícate con Google para obtener orientación adicional sobre cómo renderizar la marca de agua. Contiene metadatos sobre el anuncio que se muestra para que los publicadores los usen con el fin de determinar la fuente de los anuncios que se muestran.

En el caso de los banners, se te solicitará que proporciones la vista de banner. En el caso de los anuncios intersticiales y recompensados, se te pedirá que implementes un método show() para mostrar el anuncio más adelante. Te recomendamos que hagas que la clase que carga el anuncio también sea responsable de implementar estos métodos de anuncios.

La siguiente es una implementación de ejemplo de loadBannerAd(). Ten en cuenta que la implementación del adaptador se verá diferente, ya que este se integra en un SDK diferente.

public final class SampleRtbAdapter extends RtbAdapter {
  ...

  @Override
  public void loadBannerAd(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {

      SampleBannerRenderer bannerRenderer =
          new SampleBannerRenderer(adConfiguration, callback);
      bannerRenderer.render();
    }
}

// Renders a banner ad, and forwards callbacks to the Google Mobile Ads SDK.
public class SampleBannerRenderer implements MediationBannerAd {
  private MediationBannerAdConfiguration adConfiguration;
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback;
  private AdView adView;
  private MediationBannerAdCallback callback;

  public SampleRtbBannerRenderer(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback) {
    this.adConfiguration = adConfiguration;
    this.adLoadCallback = adLoadCallback;
  }

  public void render() {
    adView = new AdView(adConfiguration.getContext());
    adView.setAdSize(adConfiguration.getAdSize());
    // serverParameters are the parameters entered in the AdMob UI for your network.
    adView.setAdUnitId(adConfiguration.getServerParameters().getString("adUnitId"));

    // Map the callbacks from your SDK to Google's SDK.
    adView.setAdListener(new AdListener() {
      // See the next step for more information on callback mapping.
      // ...
    });

    // Get the bid response and watermark from the ad configuration and
    // pass the relevant information to your SDK.
    String ad = adConfiguration.getBidResponse();
    String watermark = adConfiguration.getWatermark();
    Bundle extras = new Bundle();
    extras.putString("bid", ad);
    extras.putString("watermark", watermark);
    AdRequest request = new AdRequest.Builder()
        .addNetworkExtrasBundle(AdMobAdapter.class, extras)
        .build();
    adView.loadAd(request);
  }

  // MediationBannerAd implementation

  @NonNull
  @Override
  public View getView() {
    return adView;
  }
}

Retransmitir eventos del ciclo de vida de presentación de anuncios

La responsabilidad final del adaptador es notificar al SDK de los anuncios móviles de Google acerca de los eventos del ciclo de vida de la presentación, de modo que puedan reenviarse al publicador. El publicador espera estas devoluciones de llamada en momentos específicos, independientemente de qué red de publicidad publique el anuncio, por lo que es importante que se invoque la mayor cantidad posible de estas devoluciones de llamada en el momento adecuado, para que el SDK de anuncios de Google para dispositivos móviles pueda reenviarlas al publicador.

Los adaptadores deben invocar los siguientes eventos cuando corresponda:

Común a todos los formatos
Método	Cuándo llamar
reportAdClicked()	Se hizo clic en el anuncio.
reportAdImpression()	El anuncio renderizó una impresión.
onAdOpened()	El anuncio presentó una vista de pantalla completa.
onAdClosed()	Se cerró la vista de pantalla completa del anuncio.
onAdLeftApplication()	El anuncio hizo que el usuario abandone la aplicación.
Anuncios recompensados
onRewarded()	El usuario recibe una recompensa.
Devoluciones de llamada de video (anuncios nativos y recompensados)
onVideoStarted()	Comenzó el video del anuncio.
onVideoCompleted()	Se completó el video del anuncio.

El adaptador recupera un objeto MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> cuando llama a mediationAdLoadCallback.onSuccess(). Se espera que los adaptadores retengan este objeto y lo usen para invocar eventos de presentación que ocurren en tu anuncio.

Por lo general, el SDK de tu red de publicidad impulsa la mayoría de estos eventos. La función del adaptador es simplemente asignar las devoluciones de llamada del SDK de tu red de publicidad al SDK de anuncios de Google para dispositivos móviles.

En el siguiente ejemplo, se muestra cómo reenviarías las devoluciones de llamada desde el objeto de escucha de anuncios de tu SDK al SDK de anuncios de Google para dispositivos móviles:

adView.setAdListener(new AdListener() {
    public void onAdLoaded() {
        callback = adLoadCallback.onSuccess(SampleBannerRenderer.this);
    }

    public void onAdImpression() {
        if (callback != null) {
            callback.reportAdImpression();
        }
    }

    public void onAdFailedToLoad(LoadAdError adError) {
        adLoadCallback.onFailure("Error: " + adError.toString());
    }

    public void onAdClosed() {
        if (callback != null) {
            callback.onAdClosed();
        }
    }

    public void onAdOpened() {
        if (callback != null) {
            callback.onAdOpened();
            callback.reportAdClicked();
        }
    }

    public void onAdLeftApplication() {
        if (callback != null) {
            callback.onAdLeftApplication();
        }
    }
});

Elementos obligatorios para el seguimiento de impresiones de anuncios nativos

El SDK de anuncios de Google para dispositivos móviles registra una impresión para un anuncio nativo cuando se puede ver 1 px del anuncio. Si el SDK de tu red de publicidad requiere que se muestren elementos específicos para renderizar una impresión válida, tu ofertante puede indicar estos elementos nativos obligatorios en la respuesta a la oferta. El SDK de anuncios de Google para dispositivos móviles valida que se muestren los elementos nativos necesarios antes de registrar una impresión.

Consulta la documentación sobre recursos nativos requeridos para obtener más información sobre cómo especificar recursos obligatorios adicionales en la respuesta a la oferta.

Punto clave: Las impresiones que se renderizan como no válidas debido a los recursos nativos obligatorios adicionales de tu red de publicidad afectarán la proporción del evento facturable para ese publicador.

Mostrar errores de anuncios

En el caso de los formatos de pantalla completa, como los intersticiales y recompensados, en la devolución de llamada de carga correcta deberás proporcionar una implementación de, MediationInterstitialAd, MediationRewardedAd para que el SDK de anuncios de Google para dispositivos móviles pueda pedirle al adaptador que muestre el anuncio.

El SDK de Google Mobile Ads espera que, si un adaptador cargó correctamente un anuncio, este esté listo para mostrarse cuando el publicador solicite mostrarlo. Esto significa que todas las llamadas a un programa deben generar una impresión.

Sin embargo, puede haber algunos casos excepcionales en los que no puedas mostrar un anuncio. Si no puedes mostrar el anuncio, llama a la devolución de llamada onAdFailedToShow() para cancelar la impresión.

En la siguiente tabla, se muestra cómo las devoluciones de llamada de presentación afectan el registro de impresiones para los formatos de anuncios de pantalla completa:

Callback	Resultado
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
Ninguna de las anteriores durante varios segundos	Impression recorded

¹ En el caso de las impresiones con errores, no se le cobra a tu red de publicidad por la impresión, pero sí afecta el ajuste de tasa de evento facturable. Consulta los indicadores de solicitud de oferta para obtener más información.

En el siguiente ejemplo de prueba, se muestra un ciclo de vida de carga o programa en el que una llamada a un programa de anuncios puede generar un error.

final class SampleRtbAdapter extends RtbAdapter implements MediationRewardedAd {

 private MediationRewardedAdCallback callback;
 private RewardedAd rewardedAd;

 ...

  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration adConfiguration,
      final MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> loadCallback) {

    // Load an ad. This mock example uses Google's SDK, but in practice
    // your adapter will load the ad using your ad network's SDK.
    RewardedAd.load(adConfiguration.getContext(),
        "ca-app-pub-3940256099942544/5224354917",
        new AdRequest.Builder().build(),
        new RewardedAdLoadCallback() {
          @Override
          public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
            // When the ad loads, invoke the load success callback.
            callback = loadCallback.onSuccess(SampleRtbAdapter.this);
          }
        });
  }

  @Override
  public void showAd(Context context) {
    // In this mock example, your ad network requires an activity context, but
    // didn't receive one, making you unable to show the ad.
    if (!(context instanceof Activity)) {
      AdError error = new AdError(1, "Context must be an activity",
          "com.google.ads.mediation.sample");
      callback.onAdFailedToShow(error);
    }

    // This example shows Google SDK's callbacks, but it's likely your SDK
    // has similar presentation callbacks.
    rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Your ad network SDK successfully showed the ad. Call onAdOpened().
        callback.onAdOpened();
      }

      @Override
      public void onAdFailedToShowFullScreenContent(AdError adError) {
        // Your ad network SDK failed to show the ad, invoke onAdFailedToShow.
        // In practice, you will map your SDK's error to an AdError.
        AdError error = new AdError(adError.getCode(), adError.getMessage(),
            adError.getDomain());
        callback.onAdFailedToShow(adError);
      }
    });


    rewardedAd.show((Activity) context, ...);
  }
}