Questa pagina è stata tradotta dall'API Cloud Translation.

Sviluppo di adattatori per offerte

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

Un adattatore per le offerte è la parte lato client dell'integrazione. L'adattatore consente all'SDK della rete pubblicitaria di comunicare con l'SDK Google Mobile Ads per caricare gli annunci pubblicati dallo strumento di offerta.

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

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 una volta completata l'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 relativi a impressioni e clic, nonché gli altri eventi relativi agli annunci che si verificano durante il ciclo di vita della presentazione dell'annuncio.

Implementazione dell'adattatore per le offerte

Per creare un adattatore per le offerte per l'SDK Google Mobile Ads, devi estendere la classe dell'estratto RtbAdapter. Le seguenti sezioni spiegano ogni metodo astratto di RtbAdapter.

getSDKVersionInfo()

A questo punto, devi restituire la versione dell'SDK. Questa versione viene passata al offerente come parte della richiesta OpenRTB.

Questo metodo richiede la restituzione di un VersionInfo. L'esempio seguente mostra come 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()

Devi restituire la versione dell'adattatore. Questa versione viene passata al 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 quattro cifre, ma VersionInfo ne consente solo l'utilizzo. 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 ciascun posizionamento e trasferire i dati pertinenti al tuo SDK per l'inizializzazione.

Quando l'SDK è stato inizializzato ed è 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.

@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 richiamato il metodo collectSignals(). Questa istanza di RtbAdapter verrà utilizzata per la durata della richiesta di annuncio, della risposta e del ciclo di vita del rendering per l'annuncio. Il metodo collectSignals() consente all'adattatore di fornire indicatori dal dispositivo da inviare al tuo strumento di offerta in una richiesta OpenRTB.

collectSignals() viene chiamata in un thread in background. L'SDK Google Mobile Ads richiede contemporaneamente gli indicatori da tutti gli adattatori che partecipano alle offerte. Sii rispettoso e limita le chiamate al thread dell'interfaccia utente durante questo periodo. Tutte le operazioni più impegnative che l'adattatore o l'SDK devono svolgere per raccogliere gli indicatori devono essere eseguite nel metodo initialize() e memorizzate nella cache.

Quando gli indicatori sono pronti, 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.

Implementare metodi di caricamento degli annunci

Timeout: 10 secondi

Se lo strumento di offerta restituisce l'offerta vincente, l'SDK Google Mobile Ads chiama l'adattatore per caricare l'annuncio vincente, trasmettendo tutti i dati restituiti dall'offerente e relativi al caricamento dell'annuncio da parte dell'SDK.

Il metodo di caricamento esatto che viene richiamato dipende dal formato dell'annuncio per il quale è stata richiesta questa richiesta:

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 chiamato nel thread dell'interfaccia utente, sulla stessa istanza dell'adattatore da cui hai fornito gli indicatori. Questo metodo fornisce i seguenti parametri:

Un elemento MediationAdConfiguration, contenente i parametri necessari all'SDK per caricare l'annuncio per l'offerta vincente, ad esempio la risposta all'offerta e le eventuali credenziali configurate dal publisher nell'interfaccia utente di AdMob.
Un oggetto MediationAdLoadCallback utilizzato per notificare all'SDK Google Mobile Ads quando il caricamento ha esito positivo o negativo.

Dopo che l'SDK ha caricato l'annuncio, chiama mediationAdLoadCallback.onSuccess(). Se il caricamento dell'annuncio dell'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 confermi una delle interfacce "Ad" definite dall'SDK Google Mobile Ads. Queste interfacce annuncio chiedono di fornire alcune informazioni sull'annuncio.

MediationAdConfiguration offre anche un metodo getWatermark() per restituire una stringa con codifica base64 che rappresenta un'immagine PNG. L'immagine deve essere affiancata in un overlay trasparente negli annunci. Contatta Google per ulteriori indicazioni su come eseguire il rendering della filigrana. Contiene metadati relativi all'annuncio mostrato per essere utilizzati 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 si occupi del caricamento degli annunci sia responsabile anche dell'implementazione di questi metodi degli annunci.

Di seguito è riportato un esempio di implementazione di loadBannerAd(). Tieni presente che l'implementazione dell'adattatore avrà un aspetto diverso poiché quest'ultimo 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;
  }
}

Inoltrare eventi del ciclo di vita della presentazione dell'annuncio

La responsabilità finale dell'adattatore è notificare all'SDK Google Mobile Ads ogni evento del ciclo di vita della presentazione, in modo che possa essere inoltrato al publisher. Il publisher prevede questi callback in momenti specifici, a prescindere dalla rete pubblicitaria che pubblica l'annuncio. È quindi importante che il maggior numero possibile di questi callback vengano richiamati al momento giusto, in modo che l'SDK Google Mobile Ads possa inoltrarli al publisher.

Gli adattatori devono richiamare i seguenti eventi quando 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 è stato visualizzato a schermo intero.
`onAdClosed()`	La visualizzazione a schermo intero dell'annuncio è stata chiusa.
`onAdLeftApplication()`	L'annuncio ha portato l'utente a uscire dall'applicazione.
Annunci con premio
`onRewarded()`	All'utente viene assegnato un premio.
Callback dei video (annunci nativi e con premio)
`onVideoStarted()`	È iniziato il video dell'annuncio.
`onVideoCompleted()`	Il video dell'annuncio è stato completato.

L'adattatore recupera un oggetto MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> al momento della chiamata a mediationAdLoadCallback.onSuccess(). Gli adattatori dovrebbero tenere l'oggetto su questo oggetto e utilizzarlo per richiamare gli eventi di presentazione che si verificano sull'annuncio.

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

L'esempio seguente mostra come inoltrare i callback dal listener 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 necessari 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 visualizzare un'impressione valida, lo strumento di offerta può indicare questi asset nativi richiesti nella risposta all'offerta. L'SDK Google Mobile Ads verifica quindi la visualizzazione degli asset nativi richiesti prima di registrare un'impressione.

Consulta la documentazione sugli asset nativi richiesti per ulteriori informazioni su come specificare gli asset obbligatori aggiuntivi nella risposta all'offerta.

Mostra errori dell'annuncio

Per i formati a schermo intero, come gli annunci interstitial e con premio, nel callback di caricamento corretto fornirai 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 adattatore ha caricato correttamente un annuncio, questo è pronto per essere mostrato quando il publisher richiede di mostrarlo. Ciò significa che ogni chiamata al programma deve generare un'impressione.

Tuttavia, possono verificarsi casi limite in cui non è possibile pubblicare un annuncio. Se non riesci a mostrare l'annuncio, chiama 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¹`
Nessuno dei precedenti per diversi secondi	`Impression recorded`

¹ In caso di impressioni non riuscite, la rete pubblicitaria non riceve alcun addebito per l'impressione, ma ciò influisce sull'aggiustamento della tariffa di eventi fatturabili. Per ulteriori informazioni, consulta gli indicatori delle richieste di offerta.

Il seguente esempio fittizio mostra un ciclo di vita di caricamento/mostra in cui una chiamata al programma dell'annuncio 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, ...);
  }
}