Desarrollo del adaptador de ofertas

Esta guía está destinada a las redes de publicidad que desean compilar un adaptador de ofertas para participar en las ofertas en tiempo real (RTB) dentro de la mediación de Google. Si eres publicador, consulta las instrucciones de mediación para publicadores.

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

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

Nota: La participación en las ofertas también requiere un ofertante que pueda responder a las solicitudes de OpenRTB. Las instrucciones para configurar 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, respuestas y adaptadores:

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

• Pasos 4 a 7: Inicializa tu 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 oferta y participe en una solicitud de RTB, y reenvíalos al SDK de anuncios de Google para dispositivos móviles.

• Pasos 18 a 21: Si tu ofertante muestra 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 los eventos de impresión y clic, así como los demás eventos de anuncios que se producen durante el ciclo de vida de presentación de tu anuncio.

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

Cómo implementar el adaptador de ofertas

Para 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 puedes convertir la versión de cadena de tu SDK en un 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 con 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 tu adaptador. Solo se llama una vez por sesión. Este método te proporciona una lista de objetos MediationConfiguration que representan la lista completa de posiciones de esta app que están configuradas para tu red de publicidad. Puedes recorrer esta lista para analizar las credenciales de cada posición y pasar los datos relevantes a tu SDK para la inicialización.

Una vez que el SDK esté inicializado y 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 apps 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 tu 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, la respuesta y la renderización del anuncio. El método collectSignals() permite que tu 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 indicadores de forma simultánea a 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 listos tus indicadores, llama a la devolución de llamada de onSuccess() con tus indicadores codificados.

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

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

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

Nota: La cadena de indicadores puede representar cualquier objeto y puede estar en cualquier formato, como JSON sin formato, codificado en Base64 o cualquier otra forma de encriptación que elijas. Se recomienda encriptar los indicadores para garantizar que sean opacos fuera de tu red.

Implementa métodos de carga de anuncios

Tiempo de espera: 10 segundos

Si tu ofertante muestra la oferta ganadora, el SDK de anuncios de Google para dispositivos móviles llama a tu adaptador para que cargue el anuncio ganador y te pasa los datos que tu ofertante mostró y que tu 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 la que proporcionaste los indicadores. Este método te proporciona los siguientes parámetros:

• Un MediationAdConfiguration, que contiene parámetros que tu SDK necesita para cargar el anuncio de la oferta ganadora, como la respuesta de la oferta y cualquier credencial 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 el SDK cargue el anuncio, llama a mediationAdLoadCallback.onSuccess(). Si falla la carga del anuncio, 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 confirme una de las interfaces "Ad" definidas por el SDK de anuncios de Google para dispositivos móviles. Estas interfaces de anuncios 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 estar en mosaico en una superposición transparente en tus anuncios. Comunícate con Google para obtener más orientación sobre cómo renderizar la marca de agua. Contiene metadatos sobre el anuncio que se muestra para que los publicadores los usen y determinen la fuente de los anuncios que se muestran.

En el caso de los banners, se te pedirá que proporciones la vista del 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. Como práctica recomendada, te sugerimos que la clase que carga el anuncio también sea responsable de implementar estos métodos de anuncios.

A continuación, se muestra una implementación de ejemplo de loadBannerAd(). Ten en cuenta que la implementación de tu adaptador se verá diferente, ya que 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;
  }
}

Reenvía eventos del ciclo de vida de la presentación de anuncios

La responsabilidad final del adaptador es notificar al SDK de anuncios de Google para dispositivos móviles sobre cualquier evento del ciclo de vida de la presentación, de modo que se pueda reenviar al publicador. El publicador espera estas devoluciones de llamada en momentos específicos, independientemente de la red de publicidad que publique el anuncio, por lo que es importante que se invoquen tantas como sea posible y 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 generó 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 saliera de la aplicación.
Anuncios recompensados
onRewarded()	Se le otorga una recompensa al usuario.
Llamadas de devolución de llamada de video (anuncios recompensados y nativos)
onVideoStarted()	Comenzó a reproducirse 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, la mayoría de estos eventos se generan a través del SDK de tu red de publicidad. El rol 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 del 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();
        }
    }
});

Recursos obligatorios para el seguimiento de impresiones de anuncios nativos

El SDK de anuncios de Google para dispositivos móviles registra una impresión de un anuncio nativo cuando se ve 1 píxel del anuncio. Si el SDK de tu red publicitaria requiere que se muestren recursos específicos para renderizar una impresión válida, tu oferta puede indicar estos recursos nativos obligatorios en la respuesta de la oferta. Luego, el SDK de anuncios de Google para dispositivos móviles valida que tus recursos nativos obligatorios se muestren antes de registrar una impresión.

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

Punto clave: Las impresiones que no sean válidas debido a los recursos nativos obligatorios adicionales de tu red de publicidad afectarán la proporción de eventos facturables de ese publicador.

Cómo mostrar errores de anuncios

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

El SDK de anuncios de Google para dispositivos móviles espera que, si un adaptador cargó correctamente un anuncio, este esté listo para mostrarse cuando el publicador lo solicite. Esto significa que cada llamada de visualización debe generar una impresión.

Sin embargo, es posible que haya casos extremos 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 la grabación de impresiones para los formatos de anuncios de pantalla completa:

Devolución de llamada	Resultado
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
Ninguna de las anteriores durante varios segundos	Impression recorded

¹ En el caso de las impresiones que fallan, no se te cobra a tu red de publicidad por la impresión, pero sí afecta el ajuste de la tasa de eventos facturables. Consulta los indicadores de solicitudes de oferta para obtener más información.

En el siguiente ejemplo simulado, se muestra un ciclo de vida de carga o visualización en el que una llamada de visualización de anuncios puede generar una falla.

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