Sviluppo di adattatori per le offerte

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

Un'opzione 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 dall'offerente.

Affinché le offerte funzionino correttamente, l'adattatore dovrà gestire l'inizializzazione, la raccolta degli indicatori, il caricamento degli annunci e la ritrasmissione degli eventi del ciclo di vita degli annunci. In questa guida ti spiegheremo come implementare l'adattatore per gestire queste operazioni.

Nota: la partecipazione all'asta richiede anche un offerente in grado di rispondere alle richieste OpenRTB. Le istruzioni su come configurare un offerente esulano dall'ambito di questa guida.

Flusso di lavoro di un'asta

Inizializzazione

Di seguito è riportato un flusso dettagliato dell'intero ciclo di vita di richiesta, risposta e rendering di un'opzione di adattamento:

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 all'offerente 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 versioni successive: durante la visualizzazione dell'annuncio, comunica all'SDK Google Mobile Ads gli eventi di impressione e clic, nonché gli altri eventi correlati all'annuncio che si verificano durante il ciclo di vita della presentazione dell'annuncio.

Nota: l'SDK Google Mobile Ads monitora separatamente gli eventi di impressione, ma è anche importante inoltrare l'evento di impressione della tua rete pubblicitaria per consentirci di verificare la presenza di discrepanze.

Implementazione dell'adattatore per le offerte

Per creare un'opzione 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 passata all'offerente nell'ambito della richiesta OpenRTB.

Questo metodo richiede di restituire un VersionInfo. L'esempio seguente mostra come puoi convertire la versione stringa del tuo 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()

Dovresti restituire la versione dell'adattatore. Questa versione viene passata all'offerente nell'ambito della richiesta OpenRTB.

Gli adattatori open source e con versione 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 solo una 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 eseguire un ciclo su questo elenco per analizzare le credenziali di ciascun posizionamento e passare i dati pertinenti all'SDK per l'inizializzazione.

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

Nota: il metodo initialize() viene chiamato su un'istanza usa e getta di un'adattatore. Non verranno chiamati altri metodi in questa particolare istanza. Se l'adattatore deve salvare lo stato in seguito all'applicazione di questo metodo, qualsiasi 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 di RtbAdapter e viene chiamato il metodo collectSignals(). Questa istanza di RtbAdapter verrà utilizzata per tutta 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 all'offerente in una richiesta OpenRTB.

collectSignals() viene chiamato in un thread in background. L'SDK Google Mobile Ads richiede contemporaneamente indicatori da tutti gli adattatori che partecipano all'asta. Rispetta le regole e limita le chiamate al thread dell'interfaccia utente durante questo periodo. Qualsiasi operazione complessa che l'adattatore o l'SDK deve eseguire per raccogliere i segnali deve essere eseguita nel metodo initialize() e memorizzata nella cache.

Una volta pronti, chiama il onSuccess() callback con i tuoi indicatori codificati.

Di seguito è riportato 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 signalCallbacks.onFailure() con una stringa che spiega l'errore che si è verificato.

Nota: la stringa di indicatori può rappresentare qualsiasi oggetto e può essere in qualsiasi formato, ad esempio JSON normale, codificato in base64 o qualsiasi altra forma di crittografia che scegli. Ti consigliamo di criptare gli indicatori per assicurarti che siano opachi al di fuori della tua rete.

Implementare i 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, passando tutti i dati che l'offerente ha restituito e di cui l'SDK ha bisogno per caricare l'annuncio.

Il metodo di caricamento esatto chiamato dipende dal formato dell'annuncio per cui viene effettuata la 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 load viene chiamato nel thread dell'interfaccia utente, nella stessa istanza dell'adattatore da cui hai fornito gli indicatori. Questo metodo fornisce i seguenti parametri:

• Un MediationAdConfiguration contenente i parametri di cui l'SDK ha bisogno per caricare l'annuncio per l'offerta vincente, ad esempio la risposta all'offerta e le eventuali credenziali del publisher configurate nell'interfaccia utente di AdMob.

• Un oggetto MediationAdLoadCallback utilizzato per notificare all'SDK Google Mobile Ads se il caricamento è riuscito o meno.

Una volta che l'SDK ha caricato l'annuncio, chiama mediationAdLoadCallback.onSuccess(). Nel caso in cui il caricamento degli annunci non vada a buon fine, chiama mediationAdLoadCallback.onFailure() con una stringa che descriva l'errore che si è verificato.

Il metodo mediationAdLoadCallback.onSuccess() richiede di passare un oggetto che sia conforme a una delle interfacce "Annuncio" definite dall'SDK Google Mobile Ads. Queste interfacce degli annunci 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 a riquadri in un overlay trasparente sugli annunci. Contatta Google per ulteriori indicazioni su come visualizzare la filigrana. Contiene metadati sull'annuncio mostrato da utilizzare dai publisher per determinare la fonte 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 gli annunci sia responsabile anche dell'implementazione di questi metodi.

Di seguito è riportata un'implementazione di esempio di loadBannerAd(). Tieni presente che l'implementazione dell'adattatore sarà diversa, poiché 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 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;
  }
}

Inoltra gli eventi del ciclo di vita della presentazione dell'annuncio

La responsabilità finale dell'adattatore è notificare 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. Pertanto, è importante che vengano richiamati il maggior numero possibile di callback e al momento giusto, in modo che l'SDK Google Mobile Ads possa inoltrarli al publisher.

Gli adattatori devono invocare i seguenti eventi, se applicabili:

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 causato l'uscita dell'utente dall'applicazione.
Annunci con premio
onRewarded()	All'utente viene concesso un premio.
Richiami video (annunci con premio e nativi)
onVideoStarted()	È iniziata la riproduzione del 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 trattenere questo oggetto e utilizzarlo per richiamare gli eventi di presentazione che si verificano nel tuo annuncio.

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

Il seguente esempio mostra come inoltrare i callback dall'ascoltatore di annunci del tuo 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 generare un'impressione valida, l'offerente può indicare questi asset nativi obbligatori nella risposta all'offerta. L'SDK Google Mobile Ads convalida quindi che gli asset nativi richiesti vengano visualizzati prima di registrare un'impressione.

Consulta la documentazione relativa agli asset obbligatori per maggiori informazioni su come specificare asset obbligatori aggiuntivi nella risposta all'offerta.

Punto chiave: tutte le impressioni non valide a causa degli asset obbligatori aggiuntivi della tua rete pubblicitaria influiranno sul rapporto di eventi fatturabili per quel publisher.

Mostrare gli errori degli annunci

Per i formati a schermo intero, come gli annunci interstitial e con premio, nel callback load di successo dovrai 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 si aspetta che, se un'entità di adattamento ha caricato correttamente un annuncio, questo sia pronto per essere visualizzato quando il publisher lo richiede. Ciò significa che ogni chiamata di visualizzazione deve generare un'impressione.

Tuttavia, potrebbero verificarsi casi limite in cui non è possibile mostrare un annuncio. Se non riesci a mostrare l'annuncio, chiama il callback onAdFailedToShow() 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 diversi secondi	Impression recorded

¹ Per le impressioni non andate a buon fine, alla rete pubblicitaria non viene addebitato alcun importo, ma influisce sull'aggiustamento del tasso di eventi fatturabili. Per ulteriori informazioni, consulta gli 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 può comportare 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, ...);
  }
}