Sviluppo di adattatori per le offerte

Questa guida è destinata alle reti pubblicitarie che vogliono creare un adattatore di offerta per partecipare alle offerte in tempo reale (RTB) all'interno della mediazione Google. Se sei un publisher, consulta le istruzioni per la mediazione per i publisher.

Un adattatore di offerta è la parte lato client dell'integrazione. L'adattatore consente all'SDK della tua rete pubblicitaria di comunicare con l'SDK Google Mobile Ads per caricare gli annunci pubblicati dal tuo offerente.

Affinché le offerte funzionino correttamente, l'adattatore deve gestire l'inizializzazione, la raccolta dei segnali, il caricamento degli annunci e la trasmissione degli eventi del ciclo di vita degli annunci. In questa guida ti mostreremo come deve essere implementato l'adattatore per gestire queste operazioni.

Nota: la partecipazione alle aste richiede anche un offerente in grado di rispondere alle richieste OpenRTB. Le istruzioni su come configurare un offerente non rientrano nell'ambito di questa guida.

Flusso di lavoro di un adattatore di offerta

Inizializzazione

Di seguito è riportato un flusso dettagliato dell'intero ciclo di vita richiesta-risposta-rendering di un adattatore:

L'adattatore è responsabile delle seguenti parti del flusso di lavoro:

• Passaggi 4-7: inizializza l'adattatore e richiama l'SDK Google Mobile Ads al termine dell'inizializzazione.

• Passaggi 10-13: raccogli gli indicatori dall'SDK della tua rete pubblicitaria da inviare al tuo bidder per partecipare a una richiesta RTB e inoltrali all'SDK Google Mobile Ads.

• Passaggi 18-21: se lo strumento di offerta restituisce l'offerta vincente, carica l'annuncio in base alla risposta dello strumento di offerta. Una volta caricato, comunica all'SDK Google Mobile Ads che l'annuncio è stato caricato.

• Passaggio 23 e successivi: mentre l'annuncio viene visualizzato, comunica all'SDK Google Mobile Ads gli eventi di impressione e clic, nonché gli altri eventi dell'annuncio che si verificano durante il ciclo di vita della presentazione dell'annuncio.

Nota: l'SDK Google Mobile Ads monitora separatamente gli eventi impressione, ma è importante anche che inoltri l'evento impressione della tua rete pubblicitaria in modo che possiamo verificare la presenza di discrepanze.

Implementazione dell'adattatore delle offerte

Per creare un adattatore di offerta per l'SDK Google Mobile Ads, devi estendere la classe astratta RtbAdapter. Le sezioni seguenti spiegano ogni metodo astratto in RtbAdapter.

getSDKVersionInfo()

Qui devi restituire la versione dell'SDK. Questa versione viene trasmessa al tuo offerente nell'ambito della richiesta OpenRTB.

Questo metodo richiede la restituzione di un VersionInfo. L'esempio seguente mostra come potresti convertire la versione stringa dell'SDK in 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()

Qui dovrebbe essere restituita la versione dell'adattatore. Questa versione viene trasmessa al tuo offerente nell'ambito della richiesta OpenRTB.

Gli adattatori open source e con controllo delle versioni di Google utilizzano uno schema di versione dell'adattatore a 4 cifre, ma VersionInfo ne consente solo 3. Per risolvere il problema, ti consigliamo di combinare le ultime due cifre nella versione della patch, come mostrato di seguito.

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

Timeout: 30 secondi

Il metodo initialize() è il primo metodo chiamato nell'adattatore. Viene chiamato una sola volta per sessione. Questo metodo fornisce un elenco di oggetti MediationConfiguration che rappresentano l'elenco completo dei posizionamenti in questa app configurati per la tua rete pubblicitaria. Puoi scorrere questo elenco per analizzare le credenziali di ogni posizionamento e passare i dati pertinenti al tuo SDK per l'inizializzazione.

Una volta inizializzato l'SDK e pronto a ricevere richieste di annuncio, richiama il metodo onInitializationSucceeded() di InitializationCompleteCallback. Questo callback viene inoltrato agli editori di app in modo che possano sapere di poter iniziare a caricare gli annunci.

Nota :il metodo initialize() viene chiamato su un'istanza temporanea di un adattatore. Non verranno chiamati altri metodi su questa particolare istanza. Se l'adattatore deve salvare lo stato in seguito a questo metodo, lo stato deve essere statico.

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

Timeout: 1 secondo

Ogni volta che il publisher richiede un annuncio, viene creata una nuova istanza del tuo RtbAdapter e viene chiamato il metodo collectSignals(). Questa istanza di RtbAdapter verrà utilizzata per la durata del ciclo di vita della richiesta, della risposta e del rendering dell'annuncio. Il metodo collectSignals() consente all'adattatore di fornire indicatori dal dispositivo da inviare al tuo offerente in una richiesta OpenRTB.

collectSignals() viene chiamato su un thread in background. L'SDK Google Mobile Ads chiede simultaneamente gli indicatori a tutti gli adattatori che partecipano all'offerta. Durante questo periodo, ti invitiamo a mostrare rispetto e a limitare le chiamate al thread UI. Qualsiasi lavoro pesante che l'adattatore o l'SDK deve svolgere per raccogliere gli indicatori deve essere eseguito nel metodo initialize() e memorizzato nella cache.

Quando i segnali sono pronti, chiama il callback onSuccess() con i segnali codificati.

Ecco un esempio di implementazione:

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

Se l'adattatore non riesce a raccogliere i segnali, chiama il numero signalCallbacks.onFailure() con una stringa che spieghi l'errore che si è verificato.

Nota :la stringa di indicatori può rappresentare qualsiasi oggetto e può essere in qualsiasi formato, ad esempio JSON semplice, codificato in Base64 o qualsiasi altra forma di crittografia che scegli. La crittografia degli indicatori è consigliata per garantire che siano opachi al di fuori della tua rete.

Implementare metodi di caricamento degli annunci

Timeout: 10 secondi

Se l'offerente restituisce l'offerta vincente, l'SDK Google Mobile Ads chiama l'adattatore per caricare l'annuncio vincente, trasmettendo tutti i dati restituiti dall'offerente necessari all'SDK per caricare l'annuncio.

Il metodo di caricamento esatto chiamato dipende dal formato dell'annuncio per cui viene effettuata questa richiesta:

Formato dell'annuncio	Metodo di caricamento
Banner	loadBannerAd()
Interstitial	loadInterstitialAd()
Con premio	loadRewardedAd()

Implementa questi metodi per i formati degli annunci supportati dall'adattatore.

Il metodo di caricamento viene chiamato sul thread UI, sulla stessa istanza dell'adattatore da cui hai fornito i segnali. Questo metodo fornisce i seguenti parametri:

• Un MediationAdConfiguration, che contiene i parametri necessari all'SDK per caricare l'annuncio per l'offerta vincente, ad esempio la risposta all'offerta e le credenziali configurate dal publisher nell'interfaccia utente di AdMob.

• Un oggetto MediationAdLoadCallback utilizzato per comunicare all'SDK Google Mobile Ads quando il caricamento ha esito positivo o negativo.

Una volta caricato l'annuncio dall'SDK, chiama mediationAdLoadCallback.onSuccess(). Se il caricamento dell'annuncio evento non va a buon fine, chiama mediationAdLoadCallback.onFailure() con una stringa che spiega l'errore che si è verificato.

Il metodo mediationAdLoadCallback.onSuccess() richiede di passare un oggetto che corrisponda a una delle interfacce "Ad" definite dall'SDK Google Mobile Ads. Queste interfacce pubblicitarie ti chiedono di fornire alcune informazioni sull'annuncio.

MediationAdConfiguration ha anche un metodo getWatermark() per restituire una stringa con codifica base64 che rappresenta un'immagine PNG. Questa immagine deve essere visualizzata in un overlay trasparente sui tuoi annunci. Contatta Google per ulteriori indicazioni su come eseguire il rendering della filigrana. Contiene metadati sull'annuncio visualizzato che vengono utilizzati dagli editori per determinare l'origine degli annunci mostrati.

Per i banner, ti verrà chiesto di fornire la visualizzazione del banner. Per gli annunci interstitial e con premio, ti verrà chiesto di implementare un metodo show() per mostrare l'annuncio in un secondo momento. Come best practice, ti consigliamo di fare in modo che la classe che carica l'annuncio sia responsabile anche dell'implementazione di questi metodi.

Di seguito è riportata un'implementazione di esempio di loadBannerAd(). Tieni presente che l'implementazione dell'adattatore avrà un aspetto diverso, in quanto l'adattatore si integra con un SDK diverso.

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

Inoltrare gli eventi del ciclo di vita della pubblicazione degli annunci

La responsabilità finale dell'adattatore è quella di comunicare all'SDK Google Mobile Ads eventuali eventi del ciclo di vita della presentazione, in modo che possano essere inoltrati al publisher. Il publisher si aspetta questi callback in momenti specifici, indipendentemente dalla rete pubblicitaria che pubblica l'annuncio, quindi è importante che il maggior numero possibile di questi callback venga richiamato al momento giusto, in modo che l'SDK Google Mobile Ads possa inoltrarli al publisher.

Gli adattatori devono richiamare i seguenti eventi, se applicabile:

Comune a tutti i formati
Metodo	Quando chiamare
reportAdClicked()	È stato fatto clic sull'annuncio.
reportAdImpression()	L'annuncio ha generato un'impressione.
onAdOpened()	L'annuncio presentava una visualizzazione a schermo intero.
onAdClosed()	La visualizzazione a schermo intero dell'annuncio è stata chiusa.
onAdLeftApplication()	L'annuncio ha indotto l'utente a uscire dall'applicazione.
Annunci con premio
onRewarded()	All'utente viene concesso un premio.
Callback video (annunci con premio e nativi)
onVideoStarted()	È iniziato il video dell'annuncio.
onVideoCompleted()	Il video dell'annuncio è stato completato.

L'adattatore riceve un oggetto MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> quando chiama mediationAdLoadCallback.onSuccess(). Gli adattatori devono conservare questo oggetto e utilizzarlo per richiamare gli eventi di presentazione che si verificano nell'annuncio.

In genere, la maggior parte di questi eventi è generata dall'SDK della rete pubblicitaria. Il ruolo dell'adattatore è semplicemente quello di mappare i callback dell'SDK della rete pubblicitaria all'SDK Google Mobile Ads.

Il seguente esempio mostra come inoltrare i callback dal listener di annunci dell'SDK all'SDK Google Mobile Ads:

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

Asset obbligatori per il monitoraggio delle impressioni degli annunci nativi

L'SDK Google Mobile Ads registra un'impressione per un annuncio nativo quando è visibile 1 px dell'annuncio. Se l'SDK della tua rete pubblicitaria richiede la visualizzazione di asset specifici per eseguire il rendering di un'impressione valida, il tuo offerente può indicare questi asset nativi richiesti nella risposta all'offerta. L'SDK Google Mobile Ads verifica quindi che gli asset nativi richiesti vengano visualizzati prima di registrare un'impressione.

Per ulteriori informazioni su come specificare asset obbligatori aggiuntivi nella risposta all'offerta, consulta la documentazione sugli asset obbligatori nativi.

Punto chiave: tutte le impressioni considerate non valide a causa degli asset nativi aggiuntivi richiesti dalla tua rete pubblicitaria influiranno sul rapporto tra eventi fatturabili per il publisher.

Mostra errori annuncio

Per i formati a schermo intero, come gli annunci interstitial e con premio, nel callback di caricamento riuscito devi fornire un'implementazione di MediationInterstitialAd o MediationRewardedAd in modo che l'SDK Google Mobile Ads possa chiedere all'adattatore di mostrare l'annuncio.

L'SDK Google Mobile Ads prevede che, se un adattatore ha caricato correttamente un annuncio, l'annuncio sia pronto per essere mostrato quando l'editore lo richiede. Ciò significa che ogni chiamata di visualizzazione deve generare un'impressione.

Tuttavia, potrebbero verificarsi casi limite in cui non è possibile pubblicare un annuncio. Se non puoi mostrare l'annuncio, chiama onAdFailedToShow() il callback per annullare l'impressione.

La tabella seguente mostra in che modo i callback di presentazione influiscono sulla registrazione delle impressioni per i formati degli annunci a schermo intero:

Richiamata	Risultato
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
Nessuna delle risposte precedenti per alcuni secondi	Impression recorded

¹ Per le impressioni non riuscite, alla tua rete pubblicitaria non viene addebitato alcun costo per l'impressione, ma ciò influisce sull'aggiustamento del tasso di eventi fatturabili. Per saperne di più, consulta la sezione Indicatori delle richieste di offerta.

Il seguente esempio simulato mostra un ciclo di vita di caricamento/visualizzazione in cui una chiamata di visualizzazione dell'annuncio potrebbe generare un errore.

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