Desenvolvimento dos adaptadores de lances

Este guia é destinado a redes de publicidade que querem criar um adaptador de lances para participar de lances em tempo real (RTB, na sigla em inglês) na mediação do Google. Se você for um publisher, consulte as instruções de mediação para publishers.

Um adaptador de lances é a parte da integração do lado do cliente. O adaptador permite que o SDK da sua rede de publicidade se comunique com Google Mobile Ads SDK para carregar anúncios veiculados pelo seu bidder.

Para que os lances funcionem corretamente, o adaptador precisa processar a inicialização, a coleta de indicadores, o carregamento de anúncios e a transmissão dos eventos do ciclo de vida deles. Neste guia, vamos mostrar como o adaptador deve ser implementado para realizar essas operações.

Fluxo de trabalho de um adaptador de lances

Inicialização

Confira abaixo o fluxo detalhado de todo o ciclo de solicitação, resposta e renderização de um adaptador:

O adaptador é responsável pelas seguintes partes do fluxo:

• Etapas 4 a 7: inicialize seu adaptador e retorne a chamada de Google Mobile Ads SDK quando a inicialização for concluída.

• Etapas 10 a 13: colete indicadores do SDK da sua rede de publicidade, que serão enviados ao bidder para que ele participe de uma solicitação de RTB e encaminhe-os ao SDK do Google.

• Etapas 18 a 21: se o bidder retornar o lance vencedor, carregue o anúncio conforme a resposta dele. Depois disso, notifique Google Mobile Ads SDK de que o anúncio foi carregado.

• Etapa 23 em diante: enquanto o anúncio estiver sendo exibido, notifique o SDK do Google sobre eventos de impressão e clique, além de outros eventos de anúncio que ocorrem durante o ciclo de apresentação dele.

Implementar o adaptador de lances

Para criar um adaptador de lances para Google Mobile Ads SDK, é necessário estender a classe abstrata RtbAdapter. Confira nas seções a seguir uma explicação de cada método abstrato em RtbAdapter.

getSDKVersionInfo()

Aqui, você precisa retornar a versão do SDK. Essa versão é transmitida ao bidder como parte da solicitação OpenRTB.

Esse método exige que você retorne um VersionInfo. O exemplo abaixo mostra como converter a versão da string do SDK em um 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()

Aqui, você precisa retornar a versão do seu adaptador. Essa versão é transmitida ao bidder como parte da solicitação OpenRTB.

Os adaptadores de código aberto e com controle de versões do Google usam um esquema de versão de adaptador de 4 dígitos, mas o VersionInfo permite apenas 3 dígitos. Para contornar isso, recomendamos combinar os últimos 2 dígitos na versão com patch, conforme mostrado abaixo.

@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()

Tempo limite: 30 segundos

O método initialize() é o primeiro chamado no seu adaptador. Ele é chamado apenas uma vez por sessão. Esse método fornece uma lista de objetos MediationConfiguration que representam a lista completa de posições no app configuradas para sua rede de publicidade. Você pode repetir essa lista para analisar as credenciais de cada posição e transmitir os dados relevantes ao seu SDK para inicialização.

Depois que seu SDK for inicializado e estiver pronto para receber solicitações de anúncios, invoque o método onInitializationSucceeded() do InitializationCompleteCallback. Esse callback é encaminhado aos publishers de apps informando que eles podem começar a carregar anúncios.

@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()

Tempo limite: 1 segundo

Cada vez que o publisher solicita um anúncio, uma nova instância do seu RtbAdapter é criada e o método collectSignals() é chamado. Essa instância de RtbAdapter será usada durante todo o ciclo de solicitação, resposta e renderização do anúncio. O método collectSignals() permite que seu adaptador forneça indicadores do dispositivo para serem enviados ao bidder em uma solicitação OpenRTB.

collectSignals() é chamado em uma linha de execução em segundo plano. Google Mobile Ads SDK solicita simultaneamente indicadores de todos os adaptadores que participam dos lances. Respeite esse período e limite as chamadas à linha de execução de interface. Qualquer trabalho pesado que seu adaptador ou SDK faça para coletar indicadores precisa ser realizado no método initialize() e armazenado em cache.

Quando os indicadores estiverem prontos, chame o callback onSuccess() com os indicadores codificados.

Confira um exemplo de implementação:

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

Se o adaptador não coletar indicadores, chame signalCallbacks.onFailure() com uma string explicando o erro que ocorreu.

Implementar métodos de carregamento de anúncios

Tempo limite: 10 segundos

Se o bidder retornar o lance vencedor, o Google Mobile Ads SDK vai chamar seu adaptador para carregar o anúncio vencedor, transmitindo todos os dados que o bidder retornou e que o SDK precisa para carregar o anúncio.

O método de carregamento exato que é chamado depende do formato do anúncio para o qual esta solicitação é feita:

Implemente esses métodos para os formatos de anúncio compatíveis com seu adaptador.

O método "load" é chamado na linha de execução da interface, na mesma instância do adaptador que você usou para fornecer indicadores. Esse método fornece os seguintes parâmetros:

• Um MediationAdConfiguration, que contém parâmetros necessários para seu SDK carregar o anúncio do lance vencedor, como a resposta do lance e quaisquer credenciais que o publisher configurou na interface da AdMob.

• Um objeto MediationAdLoadCallback usado para notificar Google Mobile Ads SDK quando o carregamento é concluído ou falha.

Depois que o SDK carregar o anúncio, chame mediationAdLoadCallback.onSuccess(). Se o carregamento do anúncio de evento falhar, chame mediationAdLoadCallback.onFailure() com uma string explicando o erro ocorrido.

O método mediationAdLoadCallback.onSuccess() exige que você transmita um objeto que esteja de acordo com uma das interfaces "Ad" definidas pelo SDK dos anúncios para dispositivos móveis do Google. Essas interfaces pedem que você forneça algumas informações sobre o anúncio.

MediationAdConfiguration também tem um método getWatermark() para retornar uma string codificada em base64 que representa uma imagem PNG. Essa imagem precisa ser organizada em blocos em uma sobreposição transparente nos seus anúncios. Entre em contato com o Google para receber mais orientações sobre como renderizar a marca-d'água. Ela contém metadados sobre o anúncio que está sendo mostrado, usados pelos publishers para determinar a origem dele.

Para banners, você precisará fornecer a visualização do banner. Para anúncios intersticiais e premiados, você precisará implementar um método show() para mostrar o anúncio em um momento posterior. Como prática recomendada, recomendamos que a classe que carrega o anúncio também seja responsável por implementar esses métodos.

Confira um exemplo de implementação de loadBannerAd(). A implementação do seu adaptador será diferente, já que ele se integra a outro SDK.

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

Transmitir eventos de ciclo de vida relacionados à apresentação de anúncios

A responsabilidade final do adaptador é notificar Google Mobile Ads SDK sobre qualquer evento do ciclo de vida da apresentação, para que eles possam ser encaminhados ao publisher. O publisher espera esses callbacks em momentos específicos, não importa qual rede de publicidade veicule o anúncio. Por isso, é importante invocar o maior número possível de callbacks no momento certo para que Google Mobile Ads SDK possa encaminhá-los ao publisher.

Os adaptadores precisam invocar os seguintes eventos quando aplicável:

O adaptador recebe um objeto MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> ao chamar mediationAdLoadCallback.onSuccess(). Espera-se que os adaptadores mantenham esse objeto e o usem para invocar eventos de apresentação que ocorrem no seu anúncio.

Normalmente, a maioria desses eventos é gerada pelo SDK da sua rede de publicidade. A função do adaptador é simplesmente mapear os callbacks do SDK da sua rede de publicidade para o Google Mobile Ads SDK.

O exemplo a seguir demonstra como encaminhar callbacks do listener de anúncios do SDK para Google Mobile Ads SDK:

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 obrigatórios para o rastreamento de impressões de anúncios nativos

O Google Mobile Ads SDK registra uma impressão de um anúncio nativo quando 1 pixel do anúncio fica visível. Se o SDK da sua rede de publicidade exigir que recursos específicos sejam exibidos para renderizar uma impressão válida, seu bidder poderá indicar essa exigência de recursos nativos na resposta do lance. Em seguida, o Google Mobile Ads SDK valida se os recursos nativos obrigatórios são exibidos antes de registrar uma impressão.

Consulte a documentação de recursos nativos obrigatórios para mais informações sobre como especificar os recursos adicionais exigidos na resposta do lance.

Mostrar erros de anúncios

Para formatos em tela cheia, como anúncios intersticiais e premiados, quando o callback de carregamento for bem-sucedido, você vai fornecer uma implementação de MediationInterstitialAd ou MediationRewardedAd para que Google Mobile Ads SDK possa pedir ao seu adaptador para mostrar o anúncio.

O Google Mobile Ads SDK pressupõe que, se um adaptador conseguiu carregar um anúncio, ele está pronto para ser exibido quando o publisher solicitar. Isso significa que cada chamada de exibição deve resultar em uma impressão.

Porém, há casos em que não é possível mostrar um anúncio. Se isso acontecer, chame o callback onAdFailedToShow() para cancelar a impressão.

A tabela abaixo mostra como os callbacks de apresentação afetam o registro de impressões para formatos de anúncio de tela cheia:

¹ No caso de impressões com falha, sua rede de publicidade não é cobrada pela impressão, mas isso afeta o ajuste da taxa de evento faturável. Consulte os indicadores de solicitação de lance para mais informações.

O exemplo ilustrativo a seguir demonstra um ciclo de carregamento/exibição em que uma chamada de exibição de anúncio pode falhar.

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