Sviluppo di adattatori per offerte

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

L'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 per caricare gli annunci pubblicati dallo strumento di offerta.

Affinché le offerte funzionino correttamente, l'adattatore deve gestire inizializzazione, raccolta di indicatori, caricamento di annunci e ciclo di vita degli annunci di inoltro eventi. In questa guida illustreremo come utilizzare l'alimentatore implementate per gestire queste operazioni.

Nota: la partecipazione alle aste richiede anche un offerente che possa rispondere Richieste OpenRTB. Le istruzioni su come promuovere un offerente non rientrano nel nell'ambito di questa guida.

Flusso di lavoro di un adattatore di offerta

Inizializzazione

Un flusso dettagliato dell'intero ciclo di vita del rendering di richiesta-risposta di un adattatore è mostrato di seguito:

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

• Passaggi 4-7: inizializza l'adattatore e richiama l'SDK Google Mobile Ads una volta completata l'inizializzazione.

• Passaggi 10-13. Raccogli gli indicatori dall'SDK della rete pubblicitaria da inviare al tuo lo strumento di offerta per partecipare a una richiesta RTB e inoltrarla al team di SDK Ads.

• Passaggi 18-21. Se l'offerente restituisce l'offerta vincente, carica l'annuncio in base alla risposta del tuo offerente. Una volta caricato, invia una notifica all'SDK Google Mobile Ads che l'annuncio è stato caricato.

• Passaggio 23 e successivi: durante la visualizzazione dell'annuncio, invia una notifica al team per gli annunci per dispositivi mobili di Google SDK degli eventi di impressione e clic, nonché degli altri eventi relativi agli annunci che si verificano durante il ciclo di vita di presentazione dell'annuncio.

di Gemini Advanced.

Nota: l'SDK Google Mobile Ads monitora separatamente gli eventi di impressione, ma importante anche che inoltri l'evento relativo alle impressioni della rete pubblicitaria, per verificare la presenza di discrepanze.

Implementazione dell'adattatore di offerte

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

getSDKVersionInfo()

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

Questo metodo richiede la restituzione di un valore VersionInfo. L'esempio seguente mostra come potresti convertire la versione della 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 nell'ambito della richiesta OpenRTB.

open source e con il controllo delle versioni adattatori utilizza uno schema di versione dell'adattatore a 4 cifre, ma VersionInfo consente cifre. Per ovviare a questo problema, si consiglia 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 solo una volta per sessione. Questo metodo fornisce un elenco MediationConfiguration oggetti che rappresentano l'elenco completo di i posizionamenti in questa app che sono configurati per la tua rete pubblicitaria; Puoi riprodurre in loop attraverso questo elenco per analizzare le credenziali per ciascun posizionamento, e passare i dati pertinenti all'SDK per l'inizializzazione.

Quando l'SDK è stato inizializzato ed è pronto a ricevere richieste di annunci, richiama il metodo Metodo onInitializationSucceeded() di InitializationCompleteCallback. Questo callback viene inoltrato ai publisher 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. Nessun altro metodo verrà chiamato su questa istanza specifica. Se l'adattatore salvando lo stato in seguito a 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 creato e viene chiamato il metodo collectSignals(). Questa istanza di Verrà usata RtbAdapter per la durata della richiesta di annuncio, della risposta e il ciclo di vita del rendering dell'annuncio. Il metodo collectSignals() attiva le tue per fornire indicatori del dispositivo da inviare all'offerente in un Richiesta OpenRTB.

collectSignals() viene chiamato in un thread in background. L'SDK Google Mobile Ads richiede contemporaneamente segnali da tutti gli adattatori che partecipano alle offerte. Sii rispettoso e limita le chiamate al thread della UI in questo periodo. Qualsiasi lavoro pesante che l'adattatore o l'SDK deve svolgere per raccogliere gli indicatori devono essere eseguiti nel metodo initialize() e memorizzati nella cache.

Quando gli indicatori sono pronti, chiama il callback onSuccess() con il tuo tramite 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 indicatori, chiama signalCallbacks.onFailure() con una stringa che spiega l'errore che si è verificato.

Nota: la stringa degli indicatori potrebbe rappresentare qualsiasi oggetto e potrebbe essere in qualsiasi standard, come JSON semplice, codificato Base64 o qualsiasi altra forma di crittografia che scegliere. Ti consigliamo di criptare i segnali per assicurarti che siano opachi all'esterno della 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, trasmettendoti tutti i dati lo strumento di offerta ha restituito che l'SDK deve caricare l'annuncio.

Il metodo di caricamento esatto chiamato dipende dall'annuncio per cui questa richiesta è rivolta:

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

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

Il metodo di caricamento viene richiamato nel thread dell'interfaccia utente, nella stessa istanza del l'adattatore da cui hai fornito gli indicatori. Questo metodo fornisce quanto segue: parametri:

• Un elemento MediationAdConfiguration, che contiene i parametri necessari per l'SDK carica l'annuncio per l'offerta vincente, ad esempio la risposta all'offerta ed eventuali credenziali dal publisher configurato nell'interfaccia utente di AdMob.

• Un oggetto MediationAdLoadCallback utilizzato per inviare una notifica all'SDK Google Mobile Ads quando il caricamento va a buon fine o meno.

Dopo che l'SDK ha caricato l'annuncio, chiama mediationAdLoadCallback.onSuccess(). Nella evento di caricamento dell'annuncio non riesce, chiama mediationAdLoadCallback.onFailure() con un stringa che spiega l'errore che si è verificato.

Il metodo mediationAdLoadCallback.onSuccess() richiede il passaggio di un che conferma uno degli elementi "Annuncio" interfacce definite dall'applicazione SDK Ads. Queste interfacce degli annunci ti chiedono di fornire alcune informazioni sull'annuncio.

MediationAdConfiguration ha anche un getWatermark() per restituire una stringa con codifica base64 che rappresenta un'immagine PNG. Questa immagine devono essere affiancati da un overlay trasparente sui tuoi annunci. Contatta Google per ulteriori indicazioni su come eseguire il rendering della filigrana. Contiene i metadati sull'annuncio pubblicato, che i publisher possono utilizzare per determinare l'origine degli annunci mostrati.

Per i banner, ti verrà chiesto di fornire la visualizzazione banner. Per interstitial e annunci con premio, ti verrà chiesto di implementare un metodo show() per pubblicare l'annuncio in un secondo momento. Come best practice, ti consigliamo di far sì che il tuo corso il caricamento degli annunci sarà responsabile anche dell'implementazione di questi metodi degli annunci.

Di seguito è riportato un esempio di implementazione di loadBannerAd(). Aspetti da tenere presenti che l'implementazione dell'adattatore avrà un aspetto diverso, si integra con un altro SDK.

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

Inoltrare eventi del ciclo di vita di presentazione dell'annuncio

La responsabilità finale dell'adattatore è informare l'SDK Google Mobile Ads. di tutti gli eventi del ciclo di vita della presentazione, in modo che possano essere inoltrati al publisher. Il publisher si aspetta che questi vengano richiamati in momenti specifici, indipendentemente quale rete pubblicitaria pubblica l'annuncio, per cui è importante che il maggior numero i callback vengono richiamati il più possibile e al momento giusto, in modo che L'SDK Mobile Ads può inoltrarli al publisher.

Gli adattatori devono richiamare i seguenti eventi, ove applicabile:

Comune a tutti i formati
Metodo	Quando chiamare
reportAdClicked()	L'annuncio ha ricevuto un clic.
reportAdImpression()	L'annuncio ha visualizzato 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 ad abbandonare l'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> alla chiamata di mediationAdLoadCallback.onSuccess(). Gli adattatori sono dovrebbe tenere questo oggetto e usarlo per richiamare gli eventi di presentazione che si verificano sul tuo annuncio.

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

L'esempio seguente mostra come inoltrare i callback dal tuo Listener di annunci dell'SDK per l'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 richiesti per il monitoraggio delle impressioni degli annunci nativi

L'SDK Google Mobile Ads registra un'impressione per un annuncio nativo quando 1 px sia visibile. Se l'SDK della tua rete pubblicitaria richiede la visualizzazione di asset specifici Per mostrare un'impressione valida, lo strumento di offerta può indicare questi requisiti obbligatori asset nativi nella risposta all'offerta. L'SDK Google Mobile Ads convalida quindi che gli asset nativi richiesti vengano visualizzati prima di registrare un'impressione.

Vedi gli asset nativi obbligatori documentazione per Ulteriori informazioni su come specificare asset obbligatori aggiuntivi nell'offerta la risposta corretta.

Punto chiave: le impressioni non valide a causa dell'aumento della gli asset nativi obbligatori influenzeranno il rapporto degli eventi fatturabili per quel publisher.

Mostra errori relativi agli annunci

Per i formati a schermo intero, come gli annunci interstitial e con premio, il callback di caricamento, fornirai un'implementazione 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 è pronto per essere pubblicato quando il publisher gli chiede di farlo. Ciò significa che ogni chiamata del podcast deve generare un'impressione.

Tuttavia, potrebbero verificarsi casi in cui non riesci a pubblicare un annuncio. Se non può mostrare l'annuncio, richiama il onAdFailedToShow() per annullare l'impressione.

La tabella seguente mostra in che modo i callback della 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 non riusciti impressioni, l'impressione non viene addebitata alla rete pubblicitaria, influisce sull'aggiustamento del tasso di eventi fatturabili. Vedi richiesta di offerta indicatori per ulteriori informazioni.

Il seguente esempio di esempio illustra un ciclo di vita di caricamento/visualizzazione in cui un annuncio mostra la chiamata potrebbe causare 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, ...);
  }
}