Desenvolvimento do adaptador de mediação da rede de anúncios

Observação :o uso do SDK dos anúncios para dispositivos móveis do Google com relação aos Serviços de Mediação é regido pelos Termos de Serviço da Mediação.

Este guia destina-se a redes de anúncios que procuram criar um adaptador de mediação. Se você é um editor, consulte as instruções de mediação do editor.

Um adaptador de rede de publicidade é a camada de comunicação entre sua rede de publicidade e a Mediação de anúncios para dispositivos móveis do Google.

O adaptador é responsável por implementar MediationBannerAdapter para oferecer suporte a anúncios de banner e MediationInterstitialAdapter para oferecer suporte a anúncios intersticiais. Ele também precisa invocar as chamadas de retorno em MediationBannerListener e MediationInterstitialListener nos momentos adequados para notificar a Mediação de anúncios para dispositivos móveis do Google sobre esses eventos, que também podem ser encaminhados ao desenvolvedor.

Rede de publicidade de exemplo

Este guia demonstra como criar um adaptador para uma rede de anúncios de amostra. A rede de publicidade de amostra contém as seguintes classes que representam as classes oferecidas pela maioria das redes de publicidade:

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

Consulte a implementação completa do SDK para mais informações sobre essas classes.

Implementar um adaptador de banner

Para implementar um adaptador compatível com anúncios de banner, crie uma classe que implemente 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() {}
}

Antes de se aprofundar na implementação do MediationBannerAdapter, vamos discutir os parâmetros do servidor, os extras de mediação e como esses valores são transmitidos para o adaptador.

Parâmetros do servidor

Sua rede de publicidade provavelmente precisa de alguns identificadores para identificar um editor. A rede de anúncios de amostra, por exemplo, exige apenas um bloco de anúncios. Esses parâmetros obrigatórios são fornecidos a você no pacote serverParameters dentro de requestBannerAd(). Durante o desenvolvimento, você pode presumir que o pacote já vai estar preenchido com as chaves necessárias:

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

A AdMob vai enviar um questionário perguntando quais parâmetros de servidor você precisa de um editor para solicitar e veicular anúncios. A AdMob usará essa entrada para configurar sua rede na IU da AdMob. A captura de tela abaixo mostra que o APID é obrigatório para a Millennial Media, e o ID do app é obrigatório para a InMobi.

A AdMob usará essas informações para preencher o pacote serverParameters ao instanciar o adaptador.

Consulte este artigo para mais informações sobre como os editores configuram redes de publicidade de mediação.

Outros parâmetros de segmentação

O MediationAdRequest contém algumas informações comuns de segmentação que podem ser usadas para segmentação de anúncios, como:

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

Extras de mediação

Caso sua rede de publicidade ofereça suporte a informações de segmentação que a MediationAdRequest não fornece, os desenvolvedores de apps podem transmitir um pacote de mediationExtras especificamente para sua rede. A mediação fornece um exemplo de como transmitir extras de mediação.

Para facilitar a transmissão opcional dessas informações para os desenvolvedores, você pode fornecer uma classe builder de pacote no adaptador. Digamos que sua rede seja compatível com a transmissão de um valor de renda. Você pode adicionar uma classe builder ao adaptador que define a renda:

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

Essa classe fornece uma API limpa para o desenvolvedor gerar um pacote para a rede:

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

Observação: mediaExtras será nulo se o desenvolvedor não fornecer nenhum extra à sua rede.

requestBannerAd()

Agora que você conheceu os parâmetros de servidor e os extras de mediação, podemos usá-los para criar um MediationBannerAdapter.

O método requestBannerAd() é chamado imediatamente após o adaptador ser instanciado. É aqui que você deve criar a visualização do anúncio e fazer uma solicitação de anúncio de banner.

Uma implementação de requestBannerAd() para a rede de anúncios de amostra fica assim:

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

Não presuma que o parâmetro de contexto é do tipo Activity. Dependendo da implementação do editor, a Mediação de anúncios para dispositivos móveis do Google pode encaminhar um contexto de aplicativo para seu adaptador. Se o adaptador não conseguir processar um contexto de aplicativo, é recomendável invocar onAdFailedToLoad() com o código de erro AdRequest.ERROR_CODE_INVALID_REQUEST.

Callbacks de MediationBannerListener

Salve o MediationBannerListener fornecido em requestBannerAd() para que você possa encaminhar eventos de anúncios de volta à Mediação de anúncios para dispositivos móveis do Google. Cada callback precisa ser invocado no momento apropriado no ciclo de vida do anúncio:

Método	Quando ligar
onAdLoaded()	A solicitação do banner foi concluída.
onAdFailedToLoad()	Falha na solicitação do banner.
onAdClicked()	O banner foi clicado.
onAdOpened()	O banner está renderizando uma visualização em tela cheia.
onAdClosed()	O usuário retorna ao app após clicar em um banner.
onAdLeftApplication()	O banner faz com que o usuário saia do app.

O adaptador de rede de publicidade de exemplo cria uma classe chamada SampleBannerEventForwarder para processar o encaminhamento de eventos:

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

Observe como o adaptador de rede de publicidade de exemplo enviou onAdClicked, onAdOpened e onAdLeftApplication no mesmo callback. Mesmo que os retornos de chamada da sua rede possam não corresponder exatamente aos retornos de chamada exigidos pelos anúncios para dispositivos móveis do Google, é responsabilidade do adaptador fornecer um mapeamento razoável.

getBannerView

Depois de chamar MediationBannerListener.onAdLoaded(), a mediação vai chamar getBannerView() para exibir a visualização do banner da sua rede de publicidade na tela. Basta retornar a visualização do banner que você criou em requestBannerAd():

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

Eventos de ciclo de vida da atividade

A mediação vai notificar o adaptador sobre os eventos de atividade onPause() e onResume() se o desenvolvedor de apps notificar a mediação dos eventos. Realize as pausas e retomadas necessárias no banner:

@Override
public void onPause() {
}

@Override
public void onResume() {
}

A rede de anúncios de amostra não inclui uma chamada de pausa ou retomada, ela fornece uma implementação vazia.

A mediação fará o possível para chamar onDestroy() quando o adaptador estiver prestes a ser destruído. Realize a limpeza necessária aqui:

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

Banners inteligentes

O SDK dos anúncios para dispositivos móveis do Google é compatível com um tamanho de banner inteligente, que é de largura total e altura variável, dependendo do tamanho do dispositivo.

Para conferir o tamanho do anúncio de um banner inteligente com precisão, o adaptador precisa usar adSize.getWidthInPixels(context) para saber a largura, e adSize.getHeightInPixels(context) em vez de adSize.getHeight() para saber a altura. Em seguida, ele deve dividir pela densidade do 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);

É possível usar widthInDp e heightInDp como o tamanho ao fazer uma solicitação de anúncio.

Observação :não use adSize.getWidth() ou adSize.getHeight() para saber o tamanho do anúncio. Os banners inteligentes são representados por uma constante de tamanho especial interna. Por isso, adSize.getWidth() e adSize.getHeight() retornam valores negativos.

Pronto! Agora você tem um adaptador de mediação para banners funcionando. Para ver uma implementação completa do SampleAdapter, clique aqui.

Implementar um adaptador intersticial

A implementação do adaptador para anúncios intersticiais é semelhante à dos anúncios de banner. Para implementar um adaptador compatível com anúncios intersticiais, crie uma classe que implemente 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 o adaptador também for compatível com banners, você pode usar a mesma classe de adaptador para implementar as duas interfaces.

Agora, familiarize-se com os parâmetros de servidor e os extras de mediação antes de continuar a implementar um MediationInterstitialAdapter.

Parâmetros de servidor (intersticial)

Consulte a seção Parâmetros de servidor de banners.

Parâmetros de segmentação adicionais (intersticial)

Consulte a seção Parâmetros de segmentação adicionais de banners.

Extras de mediação (intersticial)

Consulte a seção Extras de mediação de banners.

requestInterstitialAd

O método requestInterstitialAd() é chamado imediatamente após o adaptador ser instanciado. É aqui que você deve criar seu anúncio intersticial e fazer uma solicitação de intersticial.

Uma implementação de requestInterstitialAd() para a rede de anúncios de amostra ficaria assim:

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

Não presuma que o parâmetro de contexto é do tipo Activity. A Mediação de anúncios para dispositivos móveis do Google encaminha o contexto transmitido pelo desenvolvedor do aplicativo, e é possível que um contexto de aplicativo seja transmitido. Se o adaptador não conseguir processar um contexto de aplicativo, é recomendável invocar onAdFailedToLoad com o código de erro AdRequest.ERROR_CODE_INVALID_REQUEST.

Callbacks de MediationIntersticialListener

Salve o MediationInterstitialListener fornecido em requestInterstitialAd para que você possa encaminhar eventos de anúncios de volta à Mediação de anúncios para dispositivos móveis do Google. Cada callback precisa ser invocado no momento adequado do ciclo de vida do anúncio:

Método	Quando ligar
onAdLoaded	A solicitação do intersticial foi concluída.
onAdFailedToLoad	A solicitação do intersticial falhou.
onAdOpened	O intersticial está sendo exibido.
onAdClosed	O intersticial está fechado.
onAdLeftApplication	O intersticial faz com que o usuário saia do app.

showInterstitial

Depois de chamar MediationInterstitialListener.onAdLoaded(), aguarde até que showInterstitial() seja chamado para mostrar o intersticial. O desenvolvedor do app decide quando exibir o intersticial, o que pode ser de até vários minutos depois de ele ter sido solicitado.

A implementação de showInterstitial() é bastante simples. Mostre apenas seu objeto intersticial:

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

Eventos de ciclo de vida da atividade (intersticial)

Consulte a seção Eventos de ciclo de vida da atividade de banner.

Depois de implementar eventos de ciclo de vida da atividade, seu adaptador de mediação estará pronto para processar anúncios intersticiais. Para ver uma implementação completa do SampleAdapter, clique aqui.

Perguntas frequentes

O que devo fazer se meu adaptador só for compatível com anúncios intersticiais ou de banner, mas não com ambos?

Se o adaptador só é compatível com banners, você só precisa implementar a interface MediationBannerAdapter. Se o adaptador só for compatível com intersticiais, você só precisará implementar a interface MediationInterstitialAdapter.