Développement d'adaptateurs de médiation pour réseau publicitaire

Ce guide est destiné aux réseaux publicitaires qui souhaitent créer un adaptateur de médiation. Si vous êtes un éditeur, consultez les instructions concernant la médiation pour les éditeurs.

Un adaptateur de réseau publicitaire constitue la couche de communication entre votre réseau publicitaire et la médiation Google Mobile Ads.

L'adaptateur est chargé d'implémenter MediationBannerAdapter pour prendre en charge les bannières et MediationInterstitialAdapter pour les annonces interstitielles. Il doit également appeler les rappels dans MediationBannerListener et MediationInterstitialListener aux moments opportuns pour informer la médiation Google Mobile Ads de ces événements, qui peuvent également être transmis au développeur.

Exemple de réseau publicitaire

Ce guide explique comment créer un adaptateur pour un exemple de réseau publicitaire. L'exemple de réseau publicitaire contient les classes suivantes, qui sont représentatives des classes proposées par la plupart des réseaux publicitaires:

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

Pour en savoir plus sur ces classes, consultez la mise en œuvre complète du SDK.

Implémenter un adaptateur de bannière

Pour implémenter un adaptateur compatible avec les bannières, créez une classe qui implémente 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() {}
}

Avant d'examiner en détail l'implémentation de MediationBannerAdapter, examinons les paramètres de serveur, les options de médiation supplémentaires et la manière dont ces valeurs sont transmises à l'adaptateur.

Paramètres du serveur

Votre réseau publicitaire a probablement besoin d'un ou plusieurs identifiants pour identifier un éditeur. Le réseau publicitaire de l'exemple, par exemple, ne requiert qu'un bloc d'annonces. Ces paramètres obligatoires vous sont fournis dans le bundle serverParameters de requestBannerAd(). Pendant le développement, vous pouvez supposer que le bundle contient déjà les clés dont vous avez besoin:

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 vous envoie un questionnaire vous demandant de quels paramètres serveur vous avez besoin de la part d'un éditeur pour demander et diffuser des annonces. AdMob utilisera cette entrée pour configurer votre réseau dans son interface utilisateur. La capture d'écran ci-dessous montre que l'APID est obligatoire pour Millennial Media, tandis que l'ID de l'application est obligatoire pour InMobi.

AdMob utilisera ces informations pour renseigner le bundle serverParameters lors de l'instanciation de votre adaptateur.

Consultez cet article pour en savoir plus sur la manière dont les éditeurs configurent les réseaux publicitaires de médiation.

Paramètres de ciblage supplémentaires

Le MediationAdRequest contient des informations de ciblage courantes que vous pouvez utiliser pour le ciblage des annonces, par exemple:

Options de médiation supplémentaires

Si votre réseau publicitaire est compatible avec des informations de ciblage qui ne sont pas fournies par MediationAdRequest, les développeurs d'applications peuvent transmettre spécifiquement un groupe de mediationExtras à votre réseau. La section Médiation fournit un exemple de transmission des extras de médiation.

Pour permettre aux développeurs de transmettre plus facilement ces informations, vous pouvez fournir une classe de compilateur de bundle dans votre adaptateur. Disons que votre réseau prend en charge la transmission d’une valeur de revenu. Vous pouvez ajouter une classe de compilateur à votre adaptateur qui définit le revenu:

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

Cette classe fournit au développeur une API propre lui permettant de générer un bundle pour votre réseau:

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

requestBannerAd()

Maintenant que vous connaissez les paramètres de serveur et les extras de médiation, nous pouvons les utiliser pour créer un MediationBannerAdapter.

La méthode requestBannerAd() est appelée immédiatement après l'instanciation de l'adaptateur. C'est ici que vous devez créer votre vue d'annonce et envoyer une demande de bannière.

L'implémentation de requestBannerAd() pour le réseau publicitaire exemple se présente comme suit:

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

Ne partez pas du principe que le paramètre de contexte est de type Activity. Selon l'implémentation de l'éditeur, la médiation Google Mobile Ads peut transmettre un contexte d'application à votre adaptateur. Si votre adaptateur ne peut pas gérer un contexte d'application, nous vous recommandons d'appeler onAdFailedToLoad() avec le code d'erreur AdRequest.ERROR_CODE_INVALID_REQUEST.

Rappels MediationBannerListener

Vous devez enregistrer les MediationBannerListener qui vous ont été fournies dans requestBannerAd() afin de pouvoir transférer les événements d'annonce à la médiation Google Mobile Ads. Chaque rappel doit être invoqué au moment approprié du cycle de vie de l'annonce:

Méthode Quand appeler
onAdLoaded() La demande de bannière a bien été effectuée.
onAdFailedToLoad() Échec de la demande de bannière.
onAdClicked() L'utilisateur a cliqué sur la bannière.
onAdOpened() La bannière affiche une vue en plein écran.
onAdClosed() L'utilisateur revient dans l'application après avoir cliqué sur une bannière.
onAdLeftApplication() Celle-ci incite l'utilisateur à quitter l'application.

L'exemple d'adaptateur de réseau publicitaire crée une classe appelée SampleBannerEventForwarder pour gérer le transfert d'événements:

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

Notez que l'adaptateur de réseau publicitaire exemple a envoyé onAdClicked, onAdOpened et onAdLeftApplication dans le même rappel. Même si les rappels de votre réseau ne correspondent pas exactement à ceux requis par Google Mobile Ads, il est de la responsabilité de l'adaptateur de fournir un mappage raisonnable.

getBannerView

Une fois que vous avez appelé MediationBannerListener.onAdLoaded(), la médiation appelle getBannerView() pour que la bannière de votre réseau publicitaire s'affiche à l'écran. Il vous suffit de renvoyer la vue de la bannière que vous avez créée dans requestBannerAd():

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

Événements du cycle de vie des activités

La médiation informe l'adaptateur des événements d'activité onPause() et onResume() si le développeur de l'application la notifie. Mettez en veille et réactivez votre bannière si nécessaire:

@Override
public void onPause() {
}

@Override
public void onResume() {
}

Le réseau publicitaire exemple n'inclut pas d'appel de mise en veille ou de reprise. Il fournit donc une implémentation vide.

La médiation fera de son mieux pour appeler onDestroy() lorsque l'adaptateur est sur le point d'être détruit. Effectuez tous les nettoyages nécessaires ici:

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

Bannières intelligentes

Le SDK Google Mobile Ads accepte les bannières intelligentes, qui s'affichent sur toute la largeur et de hauteur variable en fonction de la taille de l'appareil.

Pour obtenir la taille d'annonce d'une bannière intelligente avec précision, votre adaptateur doit utiliser adSize.getWidthInPixels(context) pour obtenir la largeur et adSize.getHeightInPixels(context) au lieu de adSize.getHeight() pour obtenir la hauteur. Il doit ensuite être divisé par la densité de l'appareil:

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

Vous pouvez ensuite utiliser widthInDp et heightInDp comme taille lorsque vous effectuez une demande d'annonce.

Et voilà ! Vous disposez désormais d'un adaptateur de médiation fonctionnel pour les bannières. Pour référence, une implémentation complète de SampleAdapter est disponible ici.

Implémenter un adaptateur pour les interstitiels

L'implémentation de l'adaptateur pour les annonces interstitielles est semblable à celle des bannières. Pour implémenter un adaptateur compatible avec les annonces interstitielles, créez une classe qui implémente 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() {}
}

Si votre adaptateur est également compatible avec les bannières, vous pouvez utiliser la même classe d'adaptateur pour implémenter les deux interfaces.

Familiarisez-vous maintenant avec les paramètres du serveur et les extras de médiation avant de passer à l'implémentation d'un MediationInterstitialAdapter.

Paramètres serveur (interstitiel)

Consultez la section Paramètres du serveur de bannières.

Paramètres de ciblage supplémentaires (interstitiel)

Consultez la section Paramètres de ciblage supplémentaires de la bannière.

Options de médiation supplémentaires (interstitiel)

Consultez la section Options supplémentaires de médiation par bannière.

requestInterstitialAd

La méthode requestInterstitialAd() est appelée immédiatement après l'instanciation de l'adaptateur. C'est ici que vous devez créer votre annonce interstitielle et envoyer une demande d'interstitiel.

Une implémentation de requestInterstitialAd() pour le réseau publicitaire exemple se présenterait comme suit:

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

Ne partez pas du principe que le paramètre de contexte est de type Activity! La médiation Google Mobile Ads transmet le contexte transmis par le développeur de l'application. Il est possible qu'un contexte d'application soit transmis. Si votre adaptateur ne peut pas gérer un contexte d'application, nous vous recommandons d'appeler onAdFailedToLoad avec le code d'erreur AdRequest.ERROR_CODE_INVALID_REQUEST.

Rappels MediationInterstitielListener

Vous devez enregistrer les MediationInterstitialListener qui vous ont été fournies dans requestInterstitialAd afin de pouvoir transférer les événements d'annonce à la médiation Google Mobile Ads. Chaque rappel doit être invoqué au moment approprié du cycle de vie de l'annonce:

Méthode Quand appeler
onAdLoaded La demande d'interstitiel a bien été envoyée.
onAdFailedToLoad Échec de la demande d'interstitiel.
onAdOpened L'interstitiel est diffusé.
onAdClosed L'interstitiel est fermé.
onAdLeftApplication L'interstitiel incite l'utilisateur à quitter l'application.

showInterstitial

Une fois que vous avez appelé MediationInterstitialListener.onAdLoaded(), vous devez attendre que l'interstitiel s'affiche jusqu'à ce que showInterstitial() soit appelé. C'est le développeur de l'application qui décide quand afficher l'interstitiel, soit plusieurs minutes après la demande.

L'implémentation de showInterstitial() est assez simple. Affichez simplement votre objet interstitiel:

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

Événements du cycle de vie d'une activité (interstitiels)

Consultez la section Événements du cycle de vie de l'activité liée aux bannières.

Après avoir implémenté les événements de cycle de vie d'une activité, votre adaptateur de médiation est prêt à gérer les annonces interstitielles. Pour référence, une implémentation complète de SampleAdapter est disponible ici.

Questions fréquentes

Que faire si mon adaptateur n'est compatible qu'avec les bannières ou les annonces interstitielles, mais pas les deux ?

Si votre adaptateur n'est compatible qu'avec les bannières, il vous suffit d'implémenter l'interface MediationBannerAdapter. Si votre adaptateur n'est compatible qu'avec les interstitiels, il vous suffit d'implémenter l'interface MediationInterstitialAdapter.