Desarrollo de adaptadores de ofertas

Esta guía está dirigida a las redes de publicidad que buscan crear un adaptador de ofertas. para participar en la licitación en tiempo real (RTB) dentro de la mediación de Google. Si si es publicador, consulte la página de mediación para editores instrucciones.

El adaptador de ofertas es la parte del cliente de la integración. El adaptador permite que el SDK de la red de publicidad se comunique con el SDK de anuncios de Google para dispositivos móviles para cargar anuncios publicados por su ofertante

Para que las ofertas funcionen correctamente, tu adaptador deberá controlar la inicialización, la recopilación de indicadores, la carga de anuncios y la retransmisión de su ciclo de vida eventos. En esta guía, te explicaremos cómo debería ser tu adaptador para manejar estas operaciones.

Nota: Para participar en la licitación también se requiere un ofertante que pueda responder a Solicitudes de OpenRTB. Las instrucciones para presentar a un ofertante están fuera del en esta guía.

Flujo de trabajo de un adaptador de ofertas

Inicialización

Un flujo detallado de todo el ciclo de vida de la renderización de solicitudes y respuestas de un adaptador se muestra a continuación:

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 completada la inicialización.

• Pasos de 10 a 13: Recopila indicadores del SDK de tu red de publicidad para enviarlos a tu participar en una solicitud de RTB y reenviarlo a la SDK de Google Ads.

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

• Paso 23 y posteriores: mientras se muestra su anuncio, notificar a los anuncios de Google para celulares SDK de eventos de impresiones y clics, así como otros eventos de anuncios que ocurren durante el ciclo de vida de 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 para 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 extiende la clase abstracta RtbAdapter. Las siguientes secciones explicar cada método abstracto en RtbAdapter

getSDKVersionInfo()

Aquí deberías 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 muestres un VersionInfo. En el siguiente ejemplo, se muestra cómo puedes convertir la versión de cadena de tu SDK en 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í deberías mostrar la versión de tu adaptador. Esta versión se pasa a tu ofertante como parte de la solicitud de OpenRTB.

Google de código abierto y con control de versiones adaptadores usa un esquema de versión de adaptador de 4 dígitos, pero el VersionInfo solo permite 3 dígitos. Para solucionar este problema, se recomienda combinar los dos últimos dígitos. a 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. Sí se llama una sola vez por sesión. Este método te proporciona una lista de MediationConfiguration que representan la lista completa de las posiciones de esta aplicación que están configuradas para su red de publicidad Puedes repetir indefinidamente a través de esta lista para analizar las credenciales para cada ubicació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 SDK 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 otros métodos en esta instancia en particular. Si el adaptador necesita guardar un 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 genera una nueva instancia de tu RtbAdapter. y se llama al método collectSignals(). Esta instancia de Se usará RtbAdapter durante la solicitud de anuncio, la respuesta y el ciclo de vida de renderización de ese anuncio. El método collectSignals() habilita tu para proporcionar señales del dispositivo que se enviarán al ofertante en un 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 manera simultánea a todos los adaptadores que participa en la licitación. Respeta las llamadas y limita las llamadas al subproceso de IU. durante este tiempo. Cualquier trabajo pesado que tu adaptador o SDK deba hacer para recopilar Los indicadores deben hacerse en el método initialize() y almacenarse en caché.

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

Este es 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 señales, llama a signalCallbacks.onFailure() con una cadena que explica el error que se produjo.

Nota: La cadena de indicadores podría representar cualquier objeto y podría estar en cualquier como JSON sin formato, codificado en Base64 o cualquier otra forma de encriptación que elegir. 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 el ofertante devuelve la oferta ganadora, el SDK de anuncios de Google para dispositivos móviles llama a tu adaptador para cargar el anuncio ganador y te pasa los datos que tu el ofertante mostró que tu SDK necesita cargar ese anuncio.

El método de carga exacto al que se llama depende del anuncio formato para el que es 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 de la adaptador a partir del cual proporcionaste los indicadores. Este método te proporciona lo siguiente parámetros:

• Un 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 el publicador configurado en la IU de AdMob.

• Un objeto MediationAdLoadCallback que se usa para notificar al SDK de anuncios de Google para dispositivos móviles cuando la carga es exitosa o falla.

Una vez que el SDK cargue el anuncio, llama a mediationAdLoadCallback.onSuccess(). En la no se puede cargar el anuncio de evento, llama a mediationAdLoadCallback.onFailure() con un cadena que explica el error que ocurrió.

El método mediationAdLoadCallback.onSuccess() requiere que pases un que se confirma con uno de los objetos "Ad" definidas por la API de Google Mobile SDK de Google Ads. Estas interfaces de anuncios le solicitan que proporcione información sobre el anuncio.

MediationAdConfiguration también tiene un getWatermark(). para mostrar una cadena codificada en base64 que representa una imagen PNG. Esta imagen deben estar 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 para determinar la fuente de los anuncios que se muestran.

En el caso de los banners, se te pedirá que proporciones la vista del banner. Para anuncios intersticiales y anuncios recompensados, se te pedirá que implementes un método show() para mostrar el anuncio en en un momento posterior. Como práctica recomendada, te sugerimos hacer que tu clase ¿La carga de anuncios también es responsable de implementar estos métodos de anuncios?

A continuación, se muestra un ejemplo de implementación de loadBannerAd(). Recuerda que la implementación del adaptador se verá diferente, ya que el adaptador 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 de ciclo de vida de presentaciones de anuncios

La última responsabilidad del adaptador es notificar al SDK de anuncios de Google para dispositivos móviles. de cualquier evento del ciclo de vida de una presentación, para que pueda reenviarse al publicador. El publicador espera estas devoluciones de llamada en momentos específicos, sin importar qué red de publicidad publica el anuncio, por lo que es importante que la misma devoluciones de llamada se invocan como sea posible y en el momento correcto, para que el servidor de El SDK de anuncios para dispositivos móviles puede reenviarlos al publicador.

Los adaptadores deben invocar los siguientes eventos cuando corresponda:

Común para 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 abandonara la aplicación.
Anuncios recompensados
onRewarded()	El usuario recibe una recompensa.
Devoluciones de llamada de video (anuncios recompensados y nativos)
onVideoStarted()	Se inició el video del anuncio.
onVideoCompleted()	El video del anuncio finalizó.

El adaptador obtiene un MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> objeto de respuesta después de llamar a mediationAdLoadCallback.onSuccess(). Los adaptadores son se espera retener este objeto y usarlo para invocar eventos de presentación que ocurren en tu anuncio.

Por lo general, la mayoría de estos eventos se generan mediante el SDK de tu red de publicidad. El 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.

El siguiente ejemplo demuestra cómo reenviarías devoluciones de llamada desde tu Objeto de escucha de anuncios del SDK para el 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 ubica 1 px de la el anuncio esté visible. Si el SDK de tu red de publicidad requiere que se muestren recursos específicos para procesar una impresión válida, su ofertante puede indicar estos elementos recursos nativos en la respuesta a la oferta. Luego, el SDK de anuncios de Google para dispositivos móviles valida que se muestren los recursos nativos necesarios antes de registrar una impresión.

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

Punto clave: las impresiones que se invalidaron debido a la carga de influirán en la proporción de eventos facturables de ese publicador.

Mostrar errores de anuncios

Para los formatos de pantalla completa, como anuncios intersticiales y recompensados, en la etapa exitosa de devolución de llamada de carga, proporcionarás una implementación de MediationInterstitialAd o MediationRewardedAd para que el SDK de Google Mobile Ads pueda pedir a tu adaptador que muestre el anuncio.

El SDK de anuncios de Google para dispositivos móviles espera que, si un adaptador El anuncio está listo para mostrarse cuando el publicador lo solicite. Esto significa que cada llamada a un programa debería generar una impresión.

Sin embargo, puede haber casos excepcionales en los que no puedas mostrar un anuncio. Si no puede mostrar el anuncio, llame al onAdFailedToShow() para cancelar la impresión.

La siguiente tabla muestra cómo las devoluciones de llamada de la 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

¹ Para errores impresiones, a tu red de publicidad no se le cobra por la impresión, pero afecta tu ajuste de tarifa de eventos facturables. Ver solicitud de oferta indicadores para obtener más información información.

En el siguiente ejemplo de ejemplo, se muestra un ciclo de vida de carga y programa en el que un anuncio “Show call” podría 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, ...);
  }
}