Sviluppo di adattatori per le offerte

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

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

Affinché le offerte funzionino correttamente, l'adattatore dovrà 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 illustreremo 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 uno strumento di offerta non rientrano nell'ambito di questa guida.

Flusso di lavoro di un adattatore per le offerte

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 flusso di lavoro:

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

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

• Passaggi da 18 a 21: se il tuo offerente restituisce l'offerta vincente, carica l'annuncio in base alla risposta dell'offerente. Una volta caricato, notifica Google Mobile Ads SDK che l'annuncio è stato caricato.

• Passaggio 23 e successivi: mentre l'annuncio viene visualizzato, notifica 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 di presentazione dell'annuncio.

Nota: Google Mobile Ads SDK 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 le offerte

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

getSDKVersionInfo()

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

Questo metodo richiede di restituire 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 al tuo offerente come parte 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 consente solo 3 cifre. Per ovviare a questo 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 trasmettere 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 delle 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 istanza specifica. Se l'adattatore deve salvare lo stato come risultato 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 la durata del ciclo di vita di richiesta di annuncio, risposta e rendering per tale 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. Google Mobile Ads SDK chiede contemporaneamente gli indicatori a tutti gli adattatori che partecipano alle offerte. Ti invitiamo a rispettare e limitare le chiamate al thread dell'interfaccia utente durante questo periodo di tempo. Qualsiasi lavoro pesante che l'adattatore o l'SDK deve eseguire per raccogliere gli indicatori deve essere eseguito nel initialize() metodo e memorizzato nella cache.

Una volta che gli indicatori sono pronti, chiama il callback onSuccess() con gli indicatori codificati.

Ecco un'implementazione di esempio:

@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 semplice, codificato in Base64 o qualsiasi altra forma di crittografia scelta. 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 il tuo offerente restituisce l'offerta vincente, il Google Mobile Ads SDK 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 è stata 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 di cui l'SDK ha bisogno 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 notificare Google Mobile Ads SDK quando il caricamento ha esito positivo o negativo.

Una volta che l'SDK ha caricato l'annuncio, chiama mediationAdLoadCallback.onSuccess(). Se il caricamento dell'annuncio non riesce, chiama mediationAdLoadCallback.onFailure() con una stringa che spiega l'errore che si è verificato.

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

MediationAdConfiguration ha anche un metodo getWatermark() per restituire una stringa con codifica in base64 che rappresenta un'immagine PNG. Questa immagine deve essere affiancata in una sovrapposizione trasparente sugli annunci. Contatta Google per ulteriori indicazioni su come eseguire il rendering della filigrana. Contiene metadati sull'annuncio visualizzato per consentire ai publisher di determinare l'origine degli annunci visualizzati.

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 dell'annuncio sia anche responsabile dell'implementazione di questi metodi dell'annuncio.

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

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

Gli adattatori devono richiamare 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 ha presentato una visualizzazione di schermata a schermo intero.
onAdClosed()	La visualizzazione a schermo intero dell'annuncio è stata chiusa.
onAdLeftApplication()	L'annuncio ha fatto uscire l'utente dall'applicazione.
Annunci con premio
onRewarded()	All'utente viene concesso un premio.
Callback video (annunci con premio e nativi)
onVideoStarted()	Il video dell'annuncio è iniziato.
onVideoCompleted()	Il video dell'annuncio è stato completato.

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

In genere, la maggior parte di questi eventi è determinata 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.

L'esempio seguente mostra come inoltrare i callback dal listener degli annunci del tuo SDK a Google Mobile Ads SDK:

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 registra un'impressione per un annuncio nativo quando è visibile 1 px dell' annuncio. Se l'SDK della 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 quindi convalida che gli asset nativi obbligatori 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 nativi obbligatori.

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

Mostrare gli 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 possa chiedere all'adattatore di mostrare l'annuncio.

Google Mobile Ads SDK si aspetta che, se un adattatore ha caricato correttamente un annuncio, l'annuncio sia pronto per essere mostrato 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 onAdFailedToShow() 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:

Callback	Risultato
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
Nessuno dei precedenti per diversi secondi	Impression recorded

¹ Per le impressioni non riuscite, alla tua rete pubblicitaria non viene addebitato alcun costo per l'impressione, ma influisce sulla rettifica della tariffa degli eventi fatturabili. Per ulteriori informazioni, consulta la sezione Indicatori delle richieste di offerta.

Il seguente esempio fittizio 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, ...);
  }
}