Sviluppo di adattatori per le offerte

Questa guida è rivolta alle reti pubblicitarie che vogliono creare un adattatore per l'asta per partecipare alle offerte in tempo reale (RTB) nella mediazione di Google. Se sei un publisher, consulta le istruzioni per la mediazione per i publisher.

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

Affinché l'asta funzioni correttamente, l'adattatore deve gestire l'inizializzazione, la raccolta degli indicatori, il caricamento degli annunci e la trasmissione degli eventi del ciclo di vita degli annunci. In questa guida ti spiegheremo come implementare l'adattatore per gestire queste operazioni.

Nota: la partecipazione alle offerte 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 per l'asta

Inizializzazione

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

L'adattatore è responsabile delle seguenti parti del workflow:

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

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

• Passaggi 18-21: se il tuo strumento di offerta restituisce l'offerta vincente, carica l'annuncio in base alla risposta dello strumento di offerta. Una volta caricato, invia una notifica a Google Mobile Ads SDK (Legacy) per informare 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 di clic, nonché gli altri eventi dell'annuncio che si verificano durante il ciclo di vita della presentazione dell'annuncio.

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

Implementazione dell'adattatore per l'asta

Per creare un adattatore per l'asta per Google Mobile Ads SDK (Legacy), 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 all'offerente nell'ambito della richiesta OpenRTB.

Questo metodo richiede la restituzione di un VersionInfo. L'esempio seguente mostra come 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 devi restituire la versione dell'adattatore. Questa versione viene trasmessa 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 consente solo 3 cifre. Per ovviare a questo problema, ti consigliamo di combinare le ultime due cifre nella versione 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 eseguire un loop di questo elenco per analizzare le credenziali di ogni posizionamento e passare i dati pertinenti all'SDK per l'inizializzazione.

Una volta inizializzato l'SDK e pronto a ricevere richieste di annunci, richiama il metodo onInitializationSucceeded() di InitializationCompleteCallback. Questo callback viene inoltrato ai publisher di app in modo che sappiano 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 su questa particolare istanza. Se l'adattatore deve salvare lo stato come risultato di 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 di RtbAdapter e viene chiamato il metodo collectSignals(). Questa istanza di RtbAdapter verrà utilizzata per la durata del ciclo di vita della richiesta di annuncio, della risposta e del rendering per tale annuncio. Il metodo collectSignals() consente all'adattatore di fornire indicatori dal dispositivo da inviare all'offerente in una richiesta OpenRTB.

collectSignals() viene chiamato su un thread in background. Google Mobile Ads SDK (Legacy) richiede contemporaneamente gli indicatori a tutti gli adattatori che partecipano all'asta. Ti invitiamo a mostrare rispetto e a limitare le chiamate al thread dell'interfaccia utente durante questo periodo. Qualsiasi operazione complessa che l'adattatore o l'SDK deve eseguire per raccogliere indicatori deve essere eseguita nel metodo initialize() e memorizzata nella cache.

Una volta preparati gli indicatori, chiama il callback onSuccess() con gli 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 gli indicatori, chiama signalCallbacks.onFailure() con una stringa che spiega l'errore che si è verificato.

Nota: la stringa degli 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.

Implementa i metodi di caricamento degli annunci

Timeout: 10 secondi

Se l'offerente restituisce l'offerta vincente, Google Mobile Ads SDK (Legacy) chiama l'adattatore per caricare l'annuncio vincente, trasmettendoti tutti i dati restituiti dall'offerente 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 di caricamento viene chiamato sul thread dell'interfaccia utente, sulla stessa istanza dell'adattatore da cui hai fornito gli indicatori. 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 inviare una notifica a Google Mobile Ads SDK (Legacy) quando il caricamento va a buon fine o non riesce.

Una volta che l'SDK ha caricato l'annuncio, chiama mediationAdLoadCallback.onSuccess(). Se il caricamento dell'annuncio 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 confermi una delle interfacce "Ad" 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 affiancata in un overlay trasparente sugli annunci. Contatta Google per ulteriori indicazioni su come eseguire il rendering della filigrana. Contiene i metadati relativi all'annuncio mostrato, che i publisher possono utilizzare 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 esegue il caricamento degli annunci sia anche responsabile dell'implementazione di questi metodi degli annunci.

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

La responsabilità finale dell'adattatore è quella di informare Google Mobile Ads SDK (Legacy) di 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 il maggior numero possibile di questi callback venga richiamato al momento giusto, in modo che Google Mobile Ads SDK (Legacy) possa inoltrarli al publisher.

Gli adattatori devono richiamare i seguenti eventi, se applicabili:

Comuni a tutti i formati
Metodo	Quando chiamare
reportAdClicked()	L'annuncio ha ricevuto un clic.
reportAdImpression()	Il rendering dell'annuncio ha generato un'impressione.
onAdOpened()	L'annuncio è stato visualizzato 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()	Il video dell'annuncio è stato avviato.
onVideoCompleted()	Il video dell'annuncio è stato completato.

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

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

L'esempio seguente mostra come inoltrare i callback dal listener di annunci dell'SDK a Google Mobile Ads SDK (Legacy):

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

Google Mobile Ads SDK (Legacy) 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. Google Mobile Ads SDK (Legacy) verifica quindi che gli asset nativi richiesti vengano visualizzati prima di registrare un'impressione.

Per saperne di più su come specificare asset aggiuntivi obbligatori nella risposta all'offerta, consulta la documentazione sugli asset nativi obbligatori.

Punto chiave: le impressioni rese non valide a causa degli asset nativi aggiuntivi richiesti dalla tua rete pubblicitaria influiranno sul rapporto di eventi fatturabili per quel publisher.

Mostra errori degli annunci

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

Google Mobile Ads SDK (Legacy) si aspetta che, se un adattatore ha caricato correttamente un annuncio, quest'ultimo sia pronto per essere mostrato quando il publisher ne richiede la visualizzazione. Ciò significa che ogni chiamata show deve generare un'impressione.

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

La tabella seguente mostra l'impatto dei callback di presentazione sulla registrazione delle impressioni per i formati degli annunci a schermo intero:

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

¹ Per le impressioni non riuscite, alla tua rete pubblicitaria non viene addebitato alcun costo, ma l'aggiustamento tariffario degli eventi fatturabili viene influenzato. Per saperne di più, consulta la sezione Indicatori delle richieste di offerta.

L'esempio fittizio seguente mostra un ciclo di vita di caricamento/visualizzazione in cui una chiamata di visualizzazione dell'annuncio potrebbe non riuscire.

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