Sviluppo dell'adattatore di mediazione della rete pubblicitaria

Nota: l'utilizzo dell'SDK Google Mobile Ads in relazione ai Servizi di mediazione è regolato dai Termini di servizio di mediazione.

Questa guida è rivolta alle reti pubblicitarie che vogliono creare un adattatore di mediazione. Se sei un publisher, consulta le istruzioni per la mediazione per i publisher.

Un adattatore di rete pubblicitaria è il livello di comunicazione tra la tua rete pubblicitaria e la mediazione Google Mobile Ads.

L'adattatore è responsabile dell'implementazione di MediationBannerAdapter per supportare gli annunci banner e MediationInterstitialAdapter per supportare gli annunci interstitial. Deve inoltre richiamare i callback in MediationBannerListener e MediationInterstitialListener nei momenti opportuni per comunicare questi eventi alla mediazione Google Mobile Ads, che possono anche essere inoltrati allo sviluppatore.

Rete pubblicitaria di esempio

Questa guida illustra come creare un adattatore per una rete pubblicitaria di esempio. La rete pubblicitaria di esempio contiene le seguenti classi rappresentative delle classi offerte dalla maggior parte delle reti pubblicitarie:

class SampleAdView {
    public SampleAdView(Context context);
    public void setSize(SampleAdSize size);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void destroy();
}

class SampleAdSize {
    public SampleAdSize(int width, int height);
    public int getWidth();
    public int getHeight();
}

class SampleAdRequest {
    public SampleAdRequest();
    public void setKeywords(Set<String> keywords);
    public void setTestMode(boolean useTesting);
}

class SampleAdListener {
    public void onAdFetchSucceeded();
    public void onAdFetchFailed(SampleErrorCode code);
    public void onAdFullScreen();
    public void onAdClosed();
}

enum SampleErrorCode {
    UNKNOWN,
    BAD_REQUEST,
    NETWORK_ERROR,
    NO_INVENTORY
}

class SampleInterstitial {
    public SampleInterstitial(Context context);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void show();
    public void destroy();
}

Consulta l'implementazione completa dell'SDK per ulteriori informazioni su queste classi.

Implementare un adattatore per banner

Per implementare un adattatore che supporti gli annunci banner, crea una classe che implementi MediationBannerAdapter.

public class SampleAdapter implements MediationBannerAdapter {
    @Override
    public void requestBannerAd(
            Context context,
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View getBannerView() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

Prima di vedere in dettaglio come implementare MediationBannerAdapter, parliamo dei parametri server, degli extra di mediazione e del modo in cui questi valori vengono passati all'adattatore.

Parametri del server

È probabile che la tua rete pubblicitaria richieda uno o più identificatori per identificare un publisher. La rete pubblicitaria di esempio, ad esempio, richiede solo un'unità pubblicitaria. Questi parametri obbligatori ti vengono forniti nel bundle serverParameters all'interno di requestBannerAd(). Durante lo sviluppo, puoi presumere che nel bundle siano già presenti le chiavi necessarie:

private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

@Override
public void requestBannerAd(
        Context context,
        MediationBannerListener listener,
        Bundle serverParameters,
        AdSize adSize,
        MediationAdRequest mediationAdRequest,
        Bundle mediationExtras) {
    String adUnit = serverParameters.getString(SAMPLE_AD_UNIT_KEY);
    ...
}

AdMob ti invierà un questionario chiedendo a un publisher quali parametri del server hai bisogno per richiedere e pubblicare gli annunci. AdMob utilizzerà questo input per configurare la tua rete nell'interfaccia utente di AdMob. Il seguente screenshot mostra che l'APID è obbligatoria per Millennial Media e l'ID app per InMobi.

AdMob utilizzerà queste informazioni per compilare il pacchetto serverParameters al momento di dimostrare l'adattatore.

Consulta questo articolo per ulteriori informazioni su come i publisher configurano le reti pubblicitarie di mediazione.

Parametri di targeting aggiuntivi

Il MediationAdRequest contiene alcune informazioni comuni sul targeting che puoi utilizzare per il targeting degli annunci, ad esempio:

• getKeywords()
• isTesting()
• taggedForChildDirectedTreatment()

Extra mediazione

Se la tua rete pubblicitaria supporta informazioni di targeting non fornite dall'MediationAdRequest, gli sviluppatori di app possono trasmettere un bundle di mediationExtras specifico alla tua rete. Mediazione fornisce un esempio di come trasmettere extra di mediazione.

Per consentire agli sviluppatori di passare più facilmente queste informazioni, se vuoi, puoi fornire una classe per lo strumento per la creazione di bundle nell'adattatore. Supponiamo che la tua rete supporti il trasferimento di un valore di reddito. Puoi aggiungere nell'adattatore una classe del builder che imposta le entrate:

public static final class BundleBuilder {
    private int income;

    public BundleBuilder setIncome(int income) {
        this.income = income;
        return this;
    }

    public Bundle build() {
        Bundle bundle = new Bundle();
        bundle.putInt("income", income);
        return bundle;
    }
}

Questa classe fornisce allo sviluppatore un'API pulita per generare un bundle per la tua rete:

Bundle sampleAdapterBundle =
        new SampleAdapter.BundleBuilder().setIncome(100000).build();

Nota: gli extra di mediazione saranno nulli se lo sviluppatore non fornisce extra per la tua rete.

requestBannerAd()

Ora che conosci i parametri del server e le funzioni extra di mediazione, possiamo utilizzarli per creare un MediationBannerAdapter.

Il metodo requestBannerAd() viene chiamato immediatamente dopo aver creato un'istanza dell'adattatore. Qui devi creare la visualizzazione dell'annuncio e creare una richiesta di annuncio banner.

Un'implementazione di requestBannerAd() per la rete pubblicitaria di esempio ha il seguente aspetto:

public class SampleAdMobAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";
    private SampleAdView sampleAdView;

    @Override
    public void requestBannerAd(
            Context context, // May be an application context.
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleAdView = new SampleAdView(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleAdView.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleAdView.setSize(
                new SampleAdSize(adSize.getWidth(),adSize.getHeight()));

        sampleAdView.setAdListener(
                new SampleBannerEventForwarder(listener, this));

        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleAdView.fetchAd(request);
    }
}

Non dare per scontato che il parametro di contesto sia di tipo Activity. A seconda dell'implementazione del publisher, Mediazione Google Mobile Ads potrebbe inoltrare un contesto dell'applicazione al tuo adattatore. Se l'adattatore non riesce a gestire un contesto dell'applicazione, ti consigliamo di richiamare onAdFailedToLoad() con il codice di errore AdRequest.ERROR_CODE_INVALID_REQUEST.

Callback di MediaBannerListener

Ti consigliamo di salvare l'elemento MediationBannerListener che ti è stato fornito in requestBannerAd() in modo da poter inoltrare gli eventi annuncio alla mediazione Google Mobile Ads. Ogni callback deve essere richiamato nel momento appropriato del ciclo di vita dell'annuncio:

Metodo	Quando chiamare
onAdLoaded()	Richiesta banner riuscita.
onAdFailedToLoad()	La richiesta del banner non è andata a buon fine.
onAdClicked()	È stato fatto clic sul banner.
onAdOpened()	Il banner mostra una visualizzazione a schermo intero.
onAdClosed()	L'utente torna all'app dopo aver fatto clic su un banner.
onAdLeftApplication()	Il banner porta l'utente a uscire dall'app.

L'adattatore di rete pubblicitaria di esempio crea una classe denominata SampleBannerEventForwarder per gestire l'inoltro di eventi:

public class SampleBannerEventForwarder extends SampleAdListener {
    private MediationBannerListener mediationListener;
    private SampleAdapter adapter;

    public SampleBannerEventForwarder(
            MediationBannerListener listener, SampleAdapter adapter) {
        this.mediationListener = listener;
        this.adapter = adapter;
    }

    @Override
    public void onAdFetchSucceeded() {
        mediationListener.onAdLoaded(adapter);
    }

    @Override
    public void onAdFetchFailed(SampleErrorCode errorCode) {
        switch(errorCode) {
            case UNKNOWN:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_INTERNAL_ERROR);
                break;
            case BAD_REQUEST:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_INVALID_REQUEST);
                break;
            case NETWORK_ERROR:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_NETWORK_ERROR);
                break;
            case NO_INVENTORY:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_NO_FILL);
                break;
        }
    }

    @Override
    public void onAdFullScreen() {
        mediationListener.onAdClicked(adapter);
        mediationListener.onAdOpened(adapter);
        mediationListener.onAdLeftApplication(adapter);
    }

    @Override
    public void onAdClosed() {
        mediationListener.onAdClosed(adapter);
    }
}

Nota come l'adattatore di rete pubblicitaria di esempio ha inviato onAdClicked, onAdOpened e onAdLeftApplication nello stesso callback. Anche se i callback per la tua rete potrebbero non corrispondere esattamente ai callback richiesti da Google Mobile Ads, è responsabilità dell'adattatore fornire una mappatura ragionevole.

getBannerView

Dopo aver chiamato MediationBannerListener.onAdLoaded(), la mediazione chiamerà getBannerView() per mostrare sullo schermo la visualizzazione del banner della tua rete pubblicitaria. Restituire semplicemente la visualizzazione banner che hai creato in requestBannerAd():

@Override
public View getBannerView() {
    return sampleAdView;
}

Eventi del ciclo di vita delle attività

La mediazione notifica all'adattatore gli eventi di attività onPause() e onResume() se lo sviluppatore di app avvisa la mediazione degli eventi. Esegui le operazioni di messa in pausa e ripristino necessarie per il banner.

@Override
public void onPause() {
}

@Override
public void onResume() {
}

La rete pubblicitaria di esempio non include una pausa o una ripresa della chiamata, pertanto fornisce un'implementazione vuota.

La mediazione farà il possibile per chiamare onDestroy() quando l'adattatore sta per essere eliminato. Esegui le operazioni di pulizia necessarie qui:

@Override
public void onDestroy() {
    if (sampleAdView != null) {
        sampleAdView.destroy();
    }
}

Banner intelligenti

L'SDK Google Mobile Ads supporta le dimensioni degli annunci con banner intelligente, che corrispondono a larghezza intera e ad altezza variabile a seconda delle dimensioni del dispositivo.

Per ottenere con precisione le dimensioni dell'annuncio di un banner intelligente, l'adattatore deve utilizzare adSize.getWidthInPixels(context) per ottenere la larghezza e adSize.getHeightInPixels(context) anziché adSize.getHeight() per ottenere l'altezza. Dovrebbe quindi dividerlo per la densità del dispositivo:

int widthInPixels = adSize.getWidthInPixels(context);
int heightInPixels = adSize.getHeightInPixels(context);
DisplayMetrics displayMetrics = Resources.getSystem().getDisplayMetrics();
int widthInDp = Math.round(widthInPixels / displayMetrics.density);
int heightInDp = Math.round(heightInPixels / displayMetrics.density);

Puoi quindi utilizzare widthInDp e heightInDp come dimensioni quando effettui una richiesta di annuncio.

Nota: non utilizzare adSize.getWidth() o adSize.getHeight() per ottenere le dimensioni dell'annuncio. Poiché i banner intelligenti sono rappresentati internamente da una costante di dimensioni speciali, adSize.getWidth() e adSize.getHeight() restituiscono valori negativi.

È tutto. Ora hai un adattatore di mediazione funzionante per i banner. Come riferimento, un'implementazione completa di SampleAdapter è disponibile qui.

Implementare un adattatore interstitial

L'implementazione dell'adattatore per gli annunci interstitial è simile agli annunci banner. Per implementare un adattatore che supporti gli annunci interstitial, crea una classe che implementi MediationInterstitialAdapter:

public class SampleAdapter implements MediationInterstitialAdapter {
    @Override
    public void requestInterstitialAd(
            Context context,
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View showInterstitial() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

Se l'adattatore supporta anche i banner, puoi utilizzare la stessa classe di adattatori per implementare entrambe le interfacce.

Acquisisci familiarità con i parametri del server e le opzioni extra di mediazione prima di procedere con l'implementazione di MediationInterstitialAdapter.

Parametri server (interstitial)

Consulta la sezione Parametri del server banner.

Parametri di targeting aggiuntivi (interstitial)

Consulta la sezione Parametri di targeting aggiuntivi del banner.

Extra mediazione (interstitial)

Consulta la sezione Opzioni aggiuntive per la mediazione banner.

requestInterstitialAd

Il metodo requestInterstitialAd() viene chiamato immediatamente dopo aver creato un'istanza dell'adattatore. È qui che devi creare il tuo annuncio interstitial ed effettuare una richiesta di interstitial.

Un'implementazione di requestInterstitialAd() per la rete pubblicitaria di esempio avrebbe il seguente aspetto:

public class SampleAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

    private SampleInterstitial sampleInterstitial;

    @Override
    public void requestInterstitialAd(
            Context context, // May be an application context.
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleInterstitial = new SampleInterstitial(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleInterstitial.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleInterstitial.setAdListener(
                new SampleInterstitialEventForwarder(listener, this));

        // Make an ad request.
        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleInterstitial.fetchAd(request);
    }
}

Non dare per scontato che il parametro di contesto sia di tipo Attività. La mediazione degli annunci per dispositivi mobili di Google inoltra il contesto trasmesso dallo sviluppatore di app ed è possibile che venga trasmesso. Se l'adattatore non riesce a gestire un contesto dell'applicazione, ti consigliamo di richiamare onAdFailedToLoad con il codice di errore AdRequest.ERROR_CODE_INVALID_REQUEST.

CallbackInterstitialListener di mediazione

Salva l'elemento MediationInterstitialListener fornito in requestInterstitialAd in modo da poter inoltrare gli eventi annuncio di nuovo alla Mediazione Google Mobile Ads. Ogni callback deve essere richiamato al momento giusto del ciclo di vita dell'annuncio:

Metodo	Quando chiamare
onAdLoaded	Richiesta di interstitial riuscita.
onAdFailedToLoad	Richiesta di interstitial non riuscita.
onAdOpened	L'interstitial viene visualizzato.
onAdClosed	L'interstitial è chiuso.
onAdLeftApplication	Il messaggio interstitial induce l'utente a uscire dall'app.

showInterstitial

Dopo aver chiamato MediationInterstitialListener.onAdLoaded(), attendi di mostrare l'interstitial fino alla chiamata di showInterstitial(). Lo sviluppatore dell'app decide quando mostrare l'interstitial, anche dopo alcuni minuti.

L'implementazione per showInterstitial() è piuttosto semplice. Mostra semplicemente il tuo oggetto interstitial:

@Override
public void showInterstitial() {
    sampleInterstitial.show();
}

Eventi del ciclo di vita delle attività (interstitial)

Consulta la sezione Eventi del ciclo di vita delle attività dei banner.

Dopo aver implementato gli eventi del ciclo di vita delle attività, l'adattatore di mediazione è pronto per gestire gli annunci interstitial. Come riferimento, un'implementazione completa di SampleAdapter è disponibile qui.

Domande frequenti

Che cosa devo fare se il mio adattatore supporta solo annunci banner o interstitial, ma non entrambi?

Se l'adattatore supporta solo i banner, dovrai solo implementare l'interfaccia MediationBannerAdapter. Se l'adattatore supporta solo interstitial, devi solo implementare l'interfaccia MediationInterstitialAdapter.