Desenvolvimento do adaptador de lances

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

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

Para que os lances funcionem corretamente, seu adaptador precisa lidar inicialização, coleta de indicadores, carregamento de anúncios e redirecionamento do ciclo de vida dos anúncios eventos. Neste guia, vamos mostrar como o adaptador deve ser implementados para lidar com essas operações.

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

Fluxo de trabalho de um adaptador de lances

Inicialização

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: inicializar o adaptador e retornar a chamada do SDK dos anúncios para dispositivos móveis do Google quando a inicialização for concluída.

• Etapas 10 a 13: coletar sinais do SDK da sua rede de publicidade para enviar à sua proponente participe de uma solicitação RTB e encaminhe-o para a equipe do Google SDK de anúncios do Google.

• Etapas 18 a 21: caso o proponente retorne o lance vencedor, carregue o anúncio de acordo com à resposta do seu proponente. Depois de carregar, notifique o SDK dos anúncios para dispositivos móveis do Google. de que o anúncio foi carregado.

• Etapa 23 e posterior: enquanto seu anúncio estiver sendo exibido, notifique os anúncios para celular do Google SDK dos eventos de impressão e clique, bem como dos outros eventos de anúncio que ocorrem durante o ciclo de vida da apresentação do seu anúncio.

.

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

Como implementar o adaptador de lances

Para criar um adaptador de lances no SDK dos anúncios para dispositivos móveis do Google, você precisa: estender a classe abstrata RtbAdapter; As seções a seguir explicar cada método abstrato em RtbAdapter.

getSDKVersionInfo()

Aqui é preciso retornar a versão do SDK. Essa versão é passada para o como parte da solicitação do OpenRTB.

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

O código aberto e uma versão adaptadores usa um esquema de versão de adaptador de 4 dígitos, mas o VersionInfo permite apenas 3 dígitos. Para contornar esse problema, recomenda-se combinar os dois últimos dígitos para a 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. É chamado apenas uma vez por sessão. Esse método fornece uma lista de Objetos MediationConfiguration que representam a lista completa de posições neste app que estejam configuradas para sua rede de publicidade. Você pode fazer um loop essa lista para analisar as credenciais de cada veiculação, e transmitir dados relevantes ao SDK para inicialização.

Quando 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 do app para que eles saibam que pode 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 nesta instância específica. Se o adaptador precisa salvar o estado como resultado desse método, qualquer estado precisa 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 do RtbAdapter é criado e o método collectSignals() é chamado. Essa instância de RtbAdapter serão usados na duração da solicitação de anúncio, resposta e de processamento do anúncio. O método collectSignals() ativa para fornecer 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 indicadores de todos os adaptadores simultaneamente que participam dos lances. Tenha respeito e limite as chamadas à linha de execução de interface durante esse período. Qualquer trabalho pesado que seu adaptador ou SDK precisar fazer para coletar os indicadores precisam ser feitos no método initialize() e armazenados em cache.

Quando seus indicadores estiverem prontos, chame o callback onSuccess() com o sinais 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.

Observação :a string de indicadores pode representar qualquer objeto e estar em qualquer como JSON simples, codificação Base64 ou qualquer outra forma de criptografia que você que você escolher. É recomendável criptografar indicadores para garantir que eles sejam opacos fora dela.

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 chama seu adaptador para carregar o anúncio vencedor, passando a você todos os dados que seu proponente retornou que seu SDK precisa carregar esse anúncio.

O método de carregamento exato chamado depende da configuração Formato da solicitação:

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 seu adaptador.

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

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

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

Depois que o SDK carregar o anúncio, chame mediationAdLoadCallback.onSuccess(). Na o carregamento do anúncio de evento falhar, chame mediationAdLoadCallback.onFailure() com uma que explica o erro que ocorreu.

O método mediationAdLoadCallback.onSuccess() exige que você transmita um que confirma para um dos campos "Anúncio" interfaces definidas pelo usuário SDK de anúncios do Google. Essas interfaces de anúncios solicitam que você forneça algumas informações sobre o anúncio.

MediationAdConfiguration também tem um getWatermark() para retornar uma string codificada em base64 que representa uma imagem PNG. Esta imagem devem estar lado a lado em uma sobreposição transparente nos anúncios. Entre em contato com o Google para receber mais orientações sobre como renderizar a marca-d'água. Ele contém metadados sobre o anúncio que está sendo exibido para uso pelos editores para determinar a origem dos anúncios mostrados.

Para banners, será solicitado que você forneça a visualização do banner. Para anúncios intersticiais e você precisará implementar um método show() para exibir o anúncio em um momento posterior. Recomendamos que sua turma o carregamento de anúncios também é responsável por implementar esses métodos de anúncio.

Confira a seguir um exemplo de implementação de loadBannerAd(). Observação importante 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 de 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 de qualquer evento de ciclo de vida da apresentação, para que possam ser encaminhados para o editor. O editor espera essas chamadas de retorno em momentos específicos, não importa qual rede de publicidade veicula o anúncio. Por isso, é importante que o maior número possível retornos de chamada sejam invocados da forma mais adequada e no momento certo, para que O SDK dos anúncios para dispositivos móveis pode encaminhá-los ao editor.

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

Formatos comuns a todos
Método	Quando ligar
reportAdClicked()	O anúncio foi clicado.
reportAdImpression()	O anúncio processou uma impressão.
onAdOpened()	O anúncio apresentou uma exibição em tela cheia.
onAdClosed()	A visualização em tela cheia do anúncio foi fechada.
onAdLeftApplication()	O anúncio fez com que o usuário deixasse o 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 começou.
onVideoCompleted()	O vídeo do anúncio foi concluído.

O adaptador recebe um MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> novamente ao chamar mediationAdLoadCallback.onSuccess(). Adaptadores são precisa manter esse objeto e usá-lo para invocar eventos de apresentação que ocorrem no seu anúncio.

Normalmente, a maioria desses eventos é impulsionada pelo SDK da rede de publicidade. A função do adaptador é simplesmente mapear as chamadas de retorno do SDK da rede de publicidade para a SDK dos anúncios para dispositivos móveis do Google.

O exemplo a seguir demonstra como você encaminharia callbacks do seu Ad listener 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 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 pixel do está visível. Se o SDK da rede de publicidade exigir que recursos específicos sejam exibidos para renderizar uma impressão válida, seu proponente pode indicar que essas impressões recursos nativos na resposta do lance. Depois, o SDK dos anúncios para dispositivos móveis do Google valida que os recursos nativos necessários sejam exibidos antes de registrar uma impressão.

Confira os recursos nativos obrigatórios documentação para Mais informações sobre como especificar recursos obrigatórios adicionais no lance resposta.

Importante: todas as impressões renderizadas como inválidas devido ao impacto adicional os recursos nativos obrigatórios afetam a proporção de eventos faturáveis para esse editor.

Mostrar erros no anúncio

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

O SDK dos anúncios para dispositivos móveis do Google espera que, se um adaptador carregar um anúncio, o anúncio está pronto para ser exibido quando o editor pede. Isso significa que todas as chamadas de exibição devem resultar em uma impressão.

No entanto, em casos específicos, você não consegue mostrar um anúncio. Se você não podem mostrar o anúncio, chame o método onAdFailedToShow() para cancelar a impressão.

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

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

¹ Para com falha impressões, sua rede de publicidade não é cobrada pela impressão, mas afeta o ajuste da taxa de eventos faturáveis. Consulte solicitação de lance indicadores informações imprecisas ou inadequadas.

O exemplo simulado a seguir demonstra um ciclo de vida de carregamento/programa em que um anúncio show poderá 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, ...);
  }
}