Разработка адаптера медиации рекламной сети

Примечание. Использование вами Google Mobile Ads SDK в сочетании со службами медиации регулируется Условиями использования медиации .

Это руководство предназначено для рекламных сетей, желающих создать адаптер медиации. Если вы издатель, ознакомьтесь с инструкциями по посредничеству издателей .

Адаптер рекламной сети – это уровень связи между вашей рекламной сетью и Google Mobile Ads Mediation.

Адаптер отвечает за реализацию MediationBannerAdapter для поддержки баннерной рекламы и MediationInterstitialAdapter для поддержки межстраничной рекламы. Он также должен вызывать обратные вызовы в MediationBannerListener и MediationInterstitialListener в подходящее время, чтобы уведомить Google Mobile Ads Mediation об этих событиях, которые также можно перенаправить разработчику.

Пример рекламной сети

В этом руководстве показано, как создать адаптер для примера рекламной сети. Пример рекламной сети содержит следующие классы, типичные для классов, предлагаемых большинством рекламных сетей:

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

Дополнительную информацию об этих классах см. в полной реализации SDK .

Реализация баннерного адаптера

Чтобы реализовать адаптер, поддерживающий рекламные баннеры, создайте класс, реализующий 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() {}
}

Прежде чем мы углубимся в реализацию MediationBannerAdapter , давайте обсудим параметры сервера, дополнительные возможности медиации и то, как эти значения передаются адаптеру.

Параметры сервера

Вашей рекламной сети, вероятно, нужны идентификаторы, чтобы идентифицировать издателя. Например, для рекламной сети «Образец» требуется только рекламный блок. Эти обязательные параметры предоставляются вам в пакете serverParameters внутри requestBannerAd() . Во время разработки можно предположить, что бандл уже будет наполнен теми ключами, которые вам нужны:

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 отправит вам анкету с вопросом, какие параметры сервера вам нужны от издателя, чтобы запрашивать и показывать рекламу. AdMob будет использовать эти данные для настройки вашей сети в пользовательском интерфейсе AdMob. На снимке экрана ниже показано, что для Millennial Media требуется APID , а для InMobi — App ID .

AdMob будет использовать эту информацию для заполнения пакета serverParameters при создании экземпляра вашего адаптера.

Дополнительную информацию о том, как издатели будут настраивать рекламные сети с посредничеством, можно найти в этой статье .

Дополнительные параметры таргетинга

MediationAdRequest содержит некоторую общую информацию о таргетинге, которую вы можете использовать для таргетинга рекламы, например:

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

Дополнительные возможности медиации

Если ваша рекламная сеть поддерживает таргетинговую информацию, которую не предоставляет MediationAdRequest , разработчики приложений могут передать пакет mediationExtras специально в вашу сеть. Посредничество представляет собой пример того, как передать дополнительные материалы посредничества.

Чтобы разработчикам было проще передавать эту информацию по желанию, вы можете предоставить в адаптере класс построителя пакетов. Допустим, ваша сеть поддерживает передачу значения дохода. Вы можете добавить в адаптер класс строителя, который устанавливает доход:

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

Этот класс предоставляет разработчику чистый API для создания пакета для вашей сети:

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

Примечание. MediationExtras будет иметь значение null, если разработчик не предоставляет никаких дополнительных возможностей для вашей сети.

запросБаннерРеклама()

Теперь, когда вы познакомились с параметрами сервера и дополнительными функциями медиации, мы можем использовать их для создания MediationBannerAdapter .

Метод requestBannerAd() вызывается сразу после создания экземпляра адаптера. Здесь вам следует создать представление объявления и сделать запрос на баннерную рекламу.

Реализация requestBannerAd() для рекламной сети Sample выглядит следующим образом:

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

Не предполагайте, что параметр context имеет тип Activity . В зависимости от реализации издателя Google Mobile Ads Mediation может пересылать контекст приложения в ваш адаптер. Если ваш адаптер не может обрабатывать контекст приложения, рекомендуется вызвать onAdFailedToLoad() с кодом ошибки AdRequest.ERROR_CODE_INVALID_REQUEST .

Обратные вызовы MediationBannerListener

Вам следует сохранить MediationBannerListener , предоставленный вам в requestBannerAd() , чтобы можно было пересылать рекламные события обратно в Google Mobile Ads Mediation. Каждый обратный вызов должен быть вызван в соответствующий момент жизненного цикла объявления:

Метод	Когда звонить
onAdLoaded()	Запрос баннера выполнен успешно.
onAdFailedToLoad()	Запрос баннера не выполнен.
onAdClicked()	Баннер был кликнут.
onAdOpened()	Баннер отображается в полноэкранном режиме.
onAdClosed()	Пользователь возвращается в приложение после нажатия на баннер.
onAdLeftApplication()	Баннер заставляет пользователя покинуть приложение.

Адаптер рекламной сети Sample создает класс SampleBannerEventForwarder для обработки пересылки событий:

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

Обратите внимание, что пример адаптера рекламной сети отправил onAdClicked , onAdOpened и onAdLeftApplication в одном обратном вызове. Даже если обратные вызовы для вашей сети могут не совсем соответствовать обратным вызовам, которые требуются для Google Mobile Ads, ответственность за обеспечение разумного сопоставления лежит на адаптере.

GetBannerView

После того, как вы вызовете MediationBannerListener.onAdLoaded() , медиация вызовет getBannerView() , чтобы отобразить на экране представление баннера вашей рекламной сети. Просто верните представление баннера, которое вы создали в requestBannerAd() :

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

События жизненного цикла активности

Посредничество уведомит адаптер о событиях активности onPause() и onResume() , если разработчик приложения уведомит посредничество о событиях. Выполните любую необходимую приостановку и возобновление показа вашего баннера:

@Override
public void onPause() {
}

@Override
public void onResume() {
}

Пример рекламной сети не включает вызов паузы или возобновления, поэтому он предоставляет пустую реализацию.

Посредник приложит все усилия, чтобы вызвать onDestroy() когда адаптер вот-вот будет уничтожен. Выполните необходимую очистку здесь:

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

Смарт-баннеры

Google Mobile Ads SDK поддерживает размеры смарт-баннеров : полную ширину и переменную высоту в зависимости от размера устройства.

Чтобы точно получить размер объявления смарт-баннера, ваш адаптер должен использовать adSize.getWidthInPixels(context) для получения ширины и adSize.getHeightInPixels(context) вместо adSize.getHeight() для получения высоты. Затем его следует разделить на плотность устройства:

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

Затем вы можете использовать widthInDp и heightInDp в качестве размера при запросе объявления.

Примечание. Не используйте adSize.getWidth() или adSize.getHeight() для получения размера объявления. Смарт-баннеры внутренне представляются специальной константой размера, поэтому adSize.getWidth() и adSize.getHeight() возвращают отрицательные значения.

Вот и все! Теперь у вас есть рабочий адаптер-посредник для баннеров! Для справки, полную реализацию SampleAdapter можно найти здесь .

Реализация межстраничного адаптера

Реализация адаптера для межстраничной рекламы аналогична баннерной рекламе. Чтобы реализовать адаптер, поддерживающий межстраничную рекламу, создайте класс, реализующий 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() {}
}

Если ваш адаптер также поддерживает баннеры, вы можете использовать один и тот же класс адаптера для реализации обоих интерфейсов.

Ознакомьтесь с параметрами сервера и дополнительными функциями медиации, прежде чем приступить к реализации MediationInterstitialAdapter .

Параметры сервера (межстраничное)

См. раздел Параметры баннерного сервера .

Дополнительные параметры таргетинга (межстраничное объявление)

См. раздел Дополнительные параметры таргетинга баннера .

Дополнительные материалы медиации (межстраничное объявление)

См. раздел «Дополнительные возможности для агрегатора баннеров» .

запросМежстраничное объявление

Метод requestInterstitialAd() вызывается сразу после создания экземпляра адаптера. Здесь вам следует создать межстраничное объявление и сделать межстраничный запрос.

Реализация requestInterstitialAd() для рекламной сети Sample будет выглядеть так:

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

Не предполагайте, что параметр контекста имеет тип Activity! Google Mobile Ads Mediation пересылает контекст, переданный разработчиком приложения, и вполне возможно, что передается контекст приложения. Если ваш адаптер не может обрабатывать контекст приложения, рекомендуется вызвать onAdFailedToLoad с кодом ошибки AdRequest.ERROR_CODE_INVALID_REQUEST .

Обратные вызовы MediationInterstitialListener

Вам следует сохранить предоставленный вам MediationInterstitialListener в requestInterstitialAd , чтобы можно было пересылать рекламные события обратно в Google Mobile Ads Mediation. Каждый обратный вызов должен быть вызван в соответствующий момент жизненного цикла объявления:

Метод	Когда звонить
onAdLoaded	Межстраничный запрос выполнен успешно.
онадфаиледтолоад	Межстраничный запрос не выполнен.
onAdOpened	Промежуточное объявление показывается.
onAdClosed	Межстраничное пространство закрыто.
onAdLeftApplication	Межстраничное объявление заставляет пользователя покинуть приложение.

показатьМежстраничное объявление

После вызова MediationInterstitialListener.onAdLoaded() вам следует подождать, чтобы отобразить межстраничное объявление, пока не будет вызван showInterstitial() . Разработчик приложения решает, когда показывать межстраничное объявление, что может занять до нескольких минут после его запроса.

Реализация showInterstitial() довольно проста. Просто покажите свой промежуточный объект:

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

События жизненного цикла действия (межстраничное объявление)

См. раздел «События жизненного цикла активности баннера» .

После реализации событий жизненного цикла действий ваш адаптер медиации готов обрабатывать межстраничные объявления! Для справки, полную реализацию SampleAdapter можно найти здесь .

Часто задаваемые вопросы

Что делать, если мой адаптер поддерживает только баннерную или межстраничную рекламу, но не то и другое?

Если ваш адаптер поддерживает только баннеры, вам нужно реализовать только интерфейс MediationBannerAdapter . Если ваш адаптер поддерживает только межстраничные объявления, вам нужно реализовать только интерфейс MediationInterstitialAdapter .