Desenvolvimento do adaptador de lances

Este guia é destinado a redes de publicidade que buscam criar um adaptador de lances para participar dos lances em tempo real (RTB) na mediação do Google. Se você é um editor, consulte as instruções de mediação do editor.

Um adaptador de lances é a parte da integração do lado do cliente. O adaptador permite que o SDK da rede de publicidade se comunique com o SDK dos anúncios para dispositivos móveis do Google para carregar anúncios veiculados pelo bidder.

Para que os lances funcionem corretamente, seu adaptador precisa processar a inicialização, coletar sinais, carregar anúncios e retransmitir eventos do ciclo de vida dos anúncios. Neste guia, vamos mostrar como implementar seu adaptador para lidar com essas operações.

Observação :a participação nos lances também exige um bidder que possa responder às solicitações do OpenRTB. As instruções sobre como defender um bidder estão fora do escopo deste guia.

Fluxo de trabalho de um adaptador de lances

Inicialização

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

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

• Etapas 4 a 7: inicialize o adaptador e chame o SDK dos anúncios para dispositivos móveis do Google quando a inicialização for concluída.

• Etapas 10 a 13: colete indicadores do SDK da rede de publicidade para que o bidder participe de uma solicitação de RTB e os encaminhe ao SDK dos anúncios para dispositivos móveis do Google.

• Etapas 18 a 21: se o bidder retornar o lance vencedor, carregue o anúncio de acordo com a resposta dele. Após o carregamento, notifique o SDK dos anúncios para dispositivos móveis do Google que o anúncio foi carregado.

• Etapa 23 e mais tarde: durante a exibição do anúncio, notifique o SDK dos anúncios para dispositivos móveis do Google sobre eventos de impressão e clique, além de outros eventos que ocorrem durante o ciclo de vida da apresentação do anúncio.

Observação :o SDK dos anúncios para dispositivos móveis do Google rastreia eventos de impressão separadamente, mas também é importante que você encaminhe o evento de impressão da sua rede de publicidade para que possamos verificar discrepâncias.

Como implementar o adaptador de lances

Para criar um adaptador de lances para o SDK dos anúncios para dispositivos móveis do Google, estenda a classe abstrata RtbAdapter. As seções a seguir explicam cada método abstrato em RtbAdapter.

getSDKVersionInfo()

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

Esse método exige que você retorne um VersionInfo. O exemplo abaixo mostra como você pode converter a versão da string do seu 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ê deve retornar a versão do adaptador. Essa versão é transmitida para o bidder como parte da solicitação do OpenRTB.

Os adaptadores de código aberto e com controle de versões do Google usam um esquema de versão de adaptador de quatro dígitos, mas o VersionInfo só permite três dígitos. Para contornar esse problema, é recomendável combinar os dois últimos dígitos na versão do 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 adaptador. Ele é chamado apenas uma vez por sessão. Esse método oferece uma lista de objetos MediationConfiguration que representam a lista completa de posições no app configuradas para sua rede de publicidade. É possível percorrer essa lista para analisar as credenciais de cada posição e transmitir dados relevantes ao SDK para inicialização.

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

Observação: o método initialize() é chamado em uma instância descartável de um adaptador. Nenhum outro método será chamado nessa instância específica. Se o adaptador precisar salvar o estado como resultado desse método, qualquer estado precisará 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()

Tempo limite: 1 segundo

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

collectSignals() é chamado em uma linha de execução em segundo plano. O SDK dos anúncios para dispositivos móveis do Google solicita simultaneamente indicadores de todos os adaptadores que participam dos lances. Respeite as chamadas e limite as chamadas à linha de execução de IU durante esse período. Qualquer trabalho pesado que o adaptador ou SDK precise realizar para coletar indicadores precisa ser feito no método initialize() e armazenado em cache.

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

Veja 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 sinais, chame signalCallbacks.onFailure() com uma string explicando o erro que ocorreu.

Observação: a string de indicadores pode representar qualquer objeto e estar em qualquer formato, como JSON simples, codificado em Base64 ou qualquer outra forma de criptografia escolhida. A criptografia dos indicadores é recomendada para garantir que eles sejam opacos fora da sua rede.

Implementar métodos de carregamento de anúncios

Tempo limite: 10 segundos

Se o bidder retornar o lance vencedor, o SDK dos anúncios para dispositivos móveis do Google chamará seu adaptador para carregar o anúncio vencedor, transmitindo todos os dados retornados pelo bidder e que o SDK precisa para carregar esse anúncio.

O método de carregamento exato chamado depende do formato de anúncio a que a solicitação se destina:

Formato do anúncio	Método de carregamento
Banner	loadBannerAd()
Intersticial	loadInterstitialAd()
Premiado	loadRewardedAd()

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

O método de carregamento é chamado na linha de execução de IU, na mesma instância do adaptador de que você forneceu sinais. Esse método fornece os seguintes parâmetros:

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

• Um objeto MediationAdLoadCallback usado para notificar o SDK dos anúncios para dispositivos móveis do Google quando o carregamento é concluído ou falha.

Depois que o SDK carregar o anúncio, chame mediationAdLoadCallback.onSuccess(). Caso o carregamento do anúncio falhe, chame mediationAdLoadCallback.onFailure() com uma string explicando o erro que ocorreu.

O método mediationAdLoadCallback.onSuccess() requer que você transmita um objeto que confirme para uma das interfaces "Anúncio" 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 colocada em uma sobreposição transparente nos anúncios. Entre em contato com o Google para saber mais sobre como renderizar a marca-d'água. Ele contém metadados sobre o anúncio mostrado para que os editores possam determinar a origem dos anúncios mostrados.

Para banners, você será solicitado a fornecer a visualização de banner. Para anúncios intersticiais e premiados, será necessário implementar um método show() para exibir o anúncio posteriormente. Como prática recomendada, faça com que a classe que faz o carregamento de anúncios também seja responsável pela implementação desses métodos.

Este é um exemplo de implementação de loadBannerAd(). Lembre-se de que a implementação do adaptador será diferente, já que ele se integra a um 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;
  }
}

Redirecionar eventos do ciclo de vida da apresentação de anúncios

A responsabilidade final do adaptador é notificar o SDK dos anúncios para dispositivos móveis do Google sobre todos os eventos de ciclo de vida da apresentação para que eles possam ser encaminhados ao editor. O editor espera esses callbacks em momentos específicos, independentemente da rede de publicidade que veicula o anúncio. Por isso, é importante que o maior número possível deles seja invocado no momento certo, para que o SDK dos anúncios para dispositivos móveis do Google possa encaminhá-los ao editor.

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

Comum a todos os formatos
Método	Quando ligar
reportAdClicked()	O anúncio recebeu um clique.
reportAdImpression()	O anúncio renderizou uma impressão.
onAdOpened()	O anúncio apresentou uma visualização em tela cheia.
onAdClosed()	A visualização em tela cheia do anúncio foi fechada.
onAdLeftApplication()	O anúncio fez o usuário sair do aplicativo.
Anúncios premiados
onRewarded()	O usuário recebe uma recompensa.
Callbacks de vídeo (anúncios premiados e nativos)
onVideoStarted()	O vídeo do anúncio foi iniciado.
onVideoCompleted()	O vídeo do anúncio foi concluído.

O adaptador recebe um objeto MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> de volta 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 é acionada pelo SDK da rede de publicidade. O papel do adaptador é simplesmente mapear os callbacks do SDK da rede de publicidade ao SDK dos anúncios para dispositivos móveis do Google.

O exemplo a seguir demonstra como encaminhar callbacks do listener de anúncios do SDK para o SDK dos anúncios para dispositivos móveis do Google:

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

O SDK dos anúncios para dispositivos móveis do Google registra uma impressão de um anúncio nativo quando 1 px do anúncio está visível. Se o SDK da rede de publicidade exigir que recursos específicos sejam exibidos para renderizar uma impressão válida, o bidder poderá indicar esses recursos nativos necessários na resposta do lance. Em seguida, o SDK dos anúncios para dispositivos móveis do Google valida se os recursos nativos necessários são exibidos antes de registrar uma impressão.

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

Importante :as impressões inválidas devido a outros recursos nativos obrigatórios da rede de publicidade vão afetar a proporção de eventos faturáveis do editor.

Mostrar erros no anúncio

Para formatos de tela cheia, como anúncios intersticiais e premiados, no callback de carregamento de sucesso, você vai fornecer uma implementação de MediationInterstitialAd ou MediationRewardedAd para que o SDK dos anúncios para dispositivos móveis do Google possa solicitar que seu adaptador mostre o anúncio.

O SDK dos anúncios para dispositivos móveis do Google espera que, se um adaptador carregar um anúncio, ele estará pronto quando o editor pedir. Isso significa que cada chamada de programa deve resultar em uma impressão.

No entanto, em alguns casos, você não conseguirá exibir um anúncio. Se não for possível exibir o anúncio, 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 em tela cheia:

Callback	Resultado
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
Nenhuma das opções acima por vários segundos	Impression recorded

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

O exemplo de simulação a seguir demonstra um ciclo de vida de carregamento/exibição em que uma chamada de exibição de anúncio pode resultar em falha.

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