Opracowywanie adaptera zapośredniczenia sieci reklamowej

Uwaga: korzystanie z pakietu SDK do reklam mobilnych Google w połączeniu z usługami zapośredniczenia podlega Warunkom korzystania z zapośredniczenia.

Ten przewodnik jest przeznaczony dla sieci reklamowych, które chcą utworzyć adapter zapośredniczenia. Jeśli jesteś wydawcą, zapoznaj się z instrukcjami zapośredniczenia wydawcy.

Adapter sieci reklamowej to warstwa komunikacji między siecią reklamową a zapośredniczeniem reklam mobilnych Google.

Adapter odpowiada za wdrożenie MediationBannerAdapter w celu obsługi banerów reklamowych i MediationInterstitialAdapter, by zapewnić obsługę reklam pełnoekranowych. Musi też w odpowiednich momentach wywoływać wywołania zwrotne w MediationBannerListener i MediationInterstitialListener, aby powiadomić zapośredniczenie reklam mobilnych Google o tych zdarzeniach i które można przekazać deweloperowi.

Przykładowa sieć reklamowa

Z tego przewodnika dowiesz się, jak utworzyć adapter na potrzeby przykładowej sieci reklamowej. Przykładowa sieć reklamowa zawiera te klasy, które są reprezentatywne dla klas oferowanych przez większość sieci reklamowych:

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

Więcej informacji o tych klasach znajdziesz w opisie pełnej implementacji pakietu SDK.

Wdrożenie adaptera banera

Aby wdrożyć adapter, który obsługuje banery reklamowe, utwórz klasę z implementacją 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() {}
}

Zanim zajmiemy się implementacją MediationBannerAdapter, omówmy parametry serwera, dodatki do zapośredniczenia oraz sposób przekazywania tych wartości do adaptera.

Parametry serwera

Twoja sieć reklamowa prawdopodobnie potrzebuje identyfikatorów, aby zidentyfikować wydawcę. Przykładowa sieć reklamowa wymaga na przykład tylko jednostki reklamowej. Wymagane parametry są podane w pakiecie serverParameters w usłudze requestBannerAd(). W trakcie programowania możesz założyć, że pakiet będzie już zawierać potrzebne klucze:

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 wyśle Ci kwestionariusz z pytaniem, jakich parametrów serwera potrzebujesz od wydawcy, by wysyłać żądania i wyświetlać reklamy. AdMob użyje tych danych do skonfigurowania sieci w interfejsie AdMob. Na zrzucie ekranu poniżej widać, że w przypadku Millennial Media wymagany jest APID, a dla InMobi – identyfikator aplikacji.

AdMob użyje tych informacji do wypełnienia pakietu serverParameters podczas inicjowania adaptera.

Więcej informacji o konfigurowaniu sieci reklamowych z zapośredniczeniem przez wydawców znajdziesz w tym artykule.

Dodatkowe parametry kierowania

MediationAdRequest zawiera podstawowe informacje, których możesz używać do kierowania reklam, np.:

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

Dodatki do zapośredniczenia

Jeśli Twoja sieć reklamowa obsługuje informacje o kierowaniu, których nie podaje MediationAdRequest, deweloperzy aplikacji mogą przekazywać do Twojej sieci pakiet mediationExtras. Zapośredniczenie to przykład przekazywania dodatkowych informacji o zapośredniczeniu.

Aby ułatwić deweloperom przesyłanie tych informacji, możesz podać w adapterze klasę kreatora pakietów. Załóżmy, że Twoja sieć obsługuje przekazywanie wartości dochodu. Możesz dodać do adaptera klasę konstruktora, która określa dochód:

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

Ta klasa udostępnia czysty interfejs API, który umożliwia deweloperowi wygenerowanie pakietu dla Twojej sieci:

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

Uwaga: jeśli deweloper nie zapewni żadnych dodatków do zapośredniczenia, będzie miał wartość null.

requestBannerAd()

Po omówieniu parametrów serwera i dodatkowych funkcji zapośredniczenia możemy je wykorzystać do utworzenia MediationBannerAdapter.

Metoda requestBannerAd() jest wywoływana natychmiast po utworzeniu instancji adaptera. W tym miejscu należy utworzyć widok reklamy i wysłać żądanie banera reklamowego.

Implementacja usługi requestBannerAd() w przypadku przykładowej sieci reklamowej wygląda tak:

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

Nie zakładaj, że parametr kontekstu jest typu Activity. W zależności od wdrożenia przez wydawcę zapośredniczenie reklam mobilnych Google może przekazać kontekst aplikacji do adaptera. Jeśli adapter nie obsługuje kontekstu aplikacji, zalecamy wywołanie onAdFailedToLoad() z kodem błędu AdRequest.ERROR_CODE_INVALID_REQUEST.

Wywołania zwrotne MediationBannerListener

Zapisz MediationBannerListener w usłudze requestBannerAd(), aby móc przekazywać zdarzenia reklamowe z powrotem do zapośredniczenia reklam mobilnych Google. Każde wywołanie zwrotne należy wywołać w odpowiednim momencie cyklu życia reklamy:

Metoda	Kiedy dzwonić
onAdLoaded()	Żądanie banera zostało zrealizowane.
onAdFailedToLoad()	Nie udało się zrealizować prośby o baner.
onAdClicked()	Kliknięto baner.
onAdOpened()	Baner renderuje się w trybie pełnoekranowym.
onAdClosed()	Użytkownik wraca do aplikacji po kliknięciu banera.
onAdLeftApplication()	Baner powoduje, że użytkownik opuszcza aplikację.

Przykładowy adapter sieci reklamowej tworzy klasę o nazwie SampleBannerEventForwarder do obsługi przekierowania zdarzeń:

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

Zwróć uwagę, że przykładowy adapter sieci reklamowej wysłał w tym samym wywołaniu zwrotny onAdClicked, onAdOpened i onAdLeftApplication. Mimo że wywołania zwrotne Twojej sieci mogą nie być dokładnie takie same jak wywołania zwrotne Google Ads na telefon komórkowy, obowiązkiem adaptera jest zapewnienie rozsądnego mapowania.

getBannerView

Gdy wywołasz metodę MediationBannerListener.onAdLoaded(), zapośredniczenie wywoła metodę getBannerView(), aby na ekranie pojawił się widok banera Twojej sieci reklamowej. Po prostu przywróć widok banera utworzony w aplikacji requestBannerAd():

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

Zdarzenia cyklu życia aktywności

Jeśli deweloper aplikacji powiadomi adapter o zdarzeniach związanych z aktywnością onPause() i onResume(). Wstrzymaj i wznów wyświetlanie banera w razie potrzeby:

@Override
public void onPause() {
}

@Override
public void onResume() {
}

Przykładowa sieć reklamowa nie zawiera wywołania wstrzymywania ani wznawiania, więc udostępnia pustą implementację.

Zapośredniczenie będzie dążyć do wywołania onDestroy(), gdy adapter będzie miał zostać zniszczony. Przeprowadź niezbędne czyszczenie tutaj:

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

Banery inteligentne

Pakiet SDK do reklam mobilnych Google obsługuje rozmiar reklamy inteligentny, który ma pełną szerokość i zmienną wysokość w zależności od rozmiaru urządzenia.

Aby dokładnie określić rozmiar banera inteligentnego, musisz użyć w adapterze właściwości adSize.getWidthInPixels(context), by uzyskać szerokość, i adSize.getHeightInPixels(context), a nie adSize.getHeight(), by uzyskać wysokość. Następnie należy podzielić go przez gęstość urządzenia:

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

Następnie w żądaniu reklamy możesz użyć widthInDp i heightInDp jako rozmiaru.

Uwaga: nie używaj adSize.getWidth() ani adSize.getHeight() do uzyskiwania rozmiaru reklamy. Banery inteligentne są wewnętrznie reprezentowane przez stałą rozmiarową, więc adSize.getWidth() i adSize.getHeight() zwracają wartości ujemne.

Znakomicie. Masz teraz działający adapter zapośredniczenia dla banerów. Pełną implementację parametru SampleAdapter znajdziesz tutaj.

Implementowanie adaptera reklam pełnoekranowych

Implementacja adaptera w przypadku reklam pełnoekranowych jest podobna do banerów reklamowych. Aby wdrożyć adapter, który obsługuje reklamy pełnoekranowe, utwórz klasę implementującą 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() {}
}

Jeśli Twój adapter również obsługuje banery, możesz zaimplementować oba interfejsy, używając tej samej klasy adaptera.

Zanim wdrożysz MediationInterstitialAdapter, zapoznaj się teraz z parametrami serwera i dodatkowymi informacjami o zapośredniczeniach.

Parametry serwera (reklama pełnoekranowa)

Zobacz sekcję Parametry serwera banerów.

Dodatkowe parametry kierowania (reklamy pełnoekranowe)

Zapoznaj się z sekcją Dodatkowe parametry kierowania banerów.

Dodatki do zapośredniczenia (reklama pełnoekranowa)

Zobacz sekcję Dodatki do zapośredniczenia banerów.

requestInterstitialAd

Metoda requestInterstitialAd() jest wywoływana natychmiast po utworzeniu instancji adaptera. W tym miejscu należy utworzyć reklamę pełnoekranową i wysłać żądanie reklamy pełnoekranowej.

Implementacja usługi requestInterstitialAd() w przykładowej sieci reklamowej wyglądałaby tak:

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

Nie zakładaj, że parametr kontekstu jest typu Aktywność. Zapośredniczenie reklam mobilnych Google przekazuje kontekst przekazany przez dewelopera aplikacji. Może też przekazywać kontekst z aplikacji. Jeśli adapter nie obsługuje kontekstu aplikacji, zalecamy wywołanie onAdFailedToLoad z kodem błędu AdRequest.ERROR_CODE_INVALID_REQUEST.

Wywołania zwrotne MediationInterstitialListener

Zapisz MediationInterstitialListener w usłudze requestInterstitialAd, aby móc przekazywać zdarzenia reklamowe z powrotem do zapośredniczenia reklam mobilnych Google. Każde wywołanie zwrotne musi zostać wykonane w odpowiednim momencie cyklu życia reklamy:

Metoda	Kiedy dzwonić
onAdLoaded	Żądanie reklamy pełnoekranowej zostało zrealizowane.
onAdFailedToLoad	Nie udało się zrealizować żądania reklamy pełnoekranowej.
onAdOpened	Wyświetla się reklama pełnoekranowa.
onAdClosed	Reklama pełnoekranowa jest zamknięta.
onAdLeftApplication	Reklama pełnoekranowa powoduje, że użytkownik opuszcza aplikację.

showInterstitial

Po wywołaniu MediationInterstitialListener.onAdLoaded() poczekaj, aż reklama pełnoekranowa zostanie wyświetlona do momentu wywołania showInterstitial(). To deweloper aplikacji decyduje, kiedy wyświetlić reklamę pełnoekranową. Może to potrwać do kilku minut od wysłania prośby.

Implementacja funkcji showInterstitial() jest dość prosta. Pokaż tylko obiekt pełnoekranowy:

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

Zdarzenia cyklu życia aktywności (reklama pełnoekranowa)

Zobacz sekcję Zdarzenia cyklu życia aktywności banera.

Po zaimplementowaniu zdarzeń cyklu życia aktywności adapter zapośredniczenia jest gotowy do obsługi reklam pełnoekranowych. Pełną implementację parametru SampleAdapter znajdziesz tutaj.

Najczęstsze pytania

Co mam zrobić, jeśli mój adapter obsługuje tylko banery lub reklamy pełnoekranowe, ale nie oba jednocześnie?

Jeśli Twój adapter obsługuje tylko banery, wystarczy zaimplementować interfejs MediationBannerAdapter. Jeśli przejściówka obsługuje tylko reklamy pełnoekranowe, wystarczy zaimplementować interfejs MediationInterstitialAdapter.