Adicionar anúncios nativos a um aplicativo Android

Com a API de Anúncio Nativa, é possível criar experiências personalizadas para os anúncios mostrados no aplicativo. Ao usar essa API, em vez de receber um anúncio pronto para exibição, você recebe um grupo de propriedades do anúncio (como título, imagem e chamada para ação) para criar uma visualização personalizada na qual o anúncio é mostrado.

Certifique-se de ter concluído os guias de Introdução do Audience Network e Introdução do Android antes de continuar.

Neste guia, implementaremos o seguinte posicionamento de anúncio nativo. Você criará um anúncio nativo com estes componentes:

Visualização 1: ícone do anúncio

Visualização 2: título do anúncio

Visualização 3: rótulo patrocinado

Visualização 4: AdOptionsView

Visualização 5: MediaView

Visualização 6: contexto social

Visualização 7: corpo do anúncio

Visualização 8: botão de chamada para ação




Etapas para anúncio nativo

Etapa 1: solicitar um anúncio nativo

Etapa 2: criar o layout do seu anúncio nativo

Etapa 3: preencher o layout com os metadados do anúncio

Etapa 4: usar o MediaView

Etapa 5: carregar o anúncio sem cache automático

Inicialize o SDK do Audience Network

Este método foi adicionado ao SDK do Audience Network para Android versão 5.1.

A inicialização explícita do SDK do Audience Network para Android é exigida para a versão 5.3.0 e superiores. Consulte este documento sobre como inicializar o SDK do Audience Network para Android.

Inicialize o SDK do Audience Network antes de criar um objeto de anúncio e carregar anúncios. É recomendado fazer isso durante a inicialização do aplicativo.

public class YourApplication extends Application {
    ...
    @Override
    public void onCreate() {
        super.onCreate();
        // Initialize the Audience Network SDK
        AudienceNetworkAds.initialize(this);       
    }
    ...
}

Etapa 1: solicitar um anúncio nativo

Adicione o seguinte código à parte superior da sua Atividade para importar o SDK de Anúncios do Facebook:

import com.facebook.ads.*;

Depois, instancie um objeto NativeAd, crie um NativeAdListener e faça uma chamada para loadAd() com o listener de anúncio:

private final String TAG = "NativeAdActivity".getClass().getSimpleName();
private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd object.
    // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
    // now, while you are testing and replace it later when you have signed up.
    // While you are using this temporary code you will only get test ads and if you release
    // your code like this to the Google Play your users will not receive ads (you will get a no fill error).
    nativeAd = new NativeAd(this, "YOUR_PLACEMENT_ID");

    NativeAdListener nativeAdListener = new NativeAdListener() {
        @Override
        public void onMediaDownloaded(Ad ad) {
            // Native ad finished downloading all assets
            Log.e(TAG, "Native ad finished downloading all assets.");
        }

        @Override
        public void onError(Ad ad, AdError adError) {
        // Native ad failed to load
            Log.e(TAG, "Native ad failed to load: " + adError.getErrorMessage());
        }

        @Override
        public void onAdLoaded(Ad ad) {
            // Native ad is loaded and ready to be displayed
            Log.d(TAG, "Native ad is loaded and ready to be displayed!");
        }

        @Override
        public void onAdClicked(Ad ad) {
            // Native ad clicked
            Log.d(TAG, "Native ad clicked!");
        }

        @Override
        public void onLoggingImpression(Ad ad) {
            // Native ad impression
            Log.d(TAG, "Native ad impression logged!");
        }
    };

    // Request an ad
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .build());
}

Voltaremos mais tarde para adicionar código ao método onAdLoaded().

Etapa 2: criar o layout do seu anúncio nativo

A próxima etapa é extrair os metadados do anúncio e usar as propriedades dele para criar a interface do usuário nativa personalizada. Você pode criar a visualização personalizada em um layout .xml ou adicionar elementos em código.

Consulte as diretrizes sobre anúncios nativos antes de criar esse tipo de anúncio no seu aplicativo.

Em activity_main.xml do layout da atividade, adicione um contêiner para o Native Ad. O contêiner deve ser um com.facebook.ads.NativeAdLayout, que é um wrapper em cima de um FrameLayout com algumas funcionalidades adicionais que nos permitem renderizar um fluxo de Relatórios de Anúncios nativos na parte superior do anúncio.

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:gravity="center_horizontal"
    android:paddingTop="50dp">
    ...
    <ScrollView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:paddingBottom="50dp">

        <com.facebook.ads.NativeAdLayout
             android:id="@+id/native_ad_container"
             android:layout_width="match_parent"
             android:layout_height="wrap_content"
             android:orientation="vertical" />
     </ScrollView>
    ...
</RelativeLayout>

Crie native_ad_layout.xml de layout personalizado para o seu anúncio nativo:



Veja abaixo um exemplo de layout personalizado para o seu anúncio nativo:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/ad_unit"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:background="@android:color/white"
    android:orientation="vertical"
    android:paddingLeft="10dp"
    android:paddingRight="10dp">

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:orientation="horizontal"
        android:paddingBottom="10dp"
        android:paddingTop="10dp">

        <com.facebook.ads.MediaView
            android:id="@+id/native_ad_icon"
            android:layout_width="35dp"
            android:layout_height="35dp" />

        <LinearLayout
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:orientation="vertical"
            android:paddingLeft="5dp"
            android:paddingRight="5dp">

        <TextView
            android:id="@+id/native_ad_title"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:ellipsize="end"
            android:lines="1"
            android:textColor="@android:color/black"
            android:textSize="15sp" />

        <TextView
            android:id="@+id/native_ad_sponsored_label"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:ellipsize="end"
            android:lines="1"
            android:textColor="@android:color/darker_gray"
            android:textSize="12sp" />

    </LinearLayout>

    <LinearLayout
        android:id="@+id/ad_choices_container"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:gravity="end"
        android:orientation="horizontal" />

    </LinearLayout>

    <com.facebook.ads.MediaView
        android:id="@+id/native_ad_media"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:gravity="center" />

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:orientation="horizontal"
        android:padding="5dp">

        <LinearLayout
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_weight="3"
            android:orientation="vertical">

            <TextView
                android:id="@+id/native_ad_social_context"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:ellipsize="end"
                android:lines="1"
                android:textColor="@android:color/darker_gray"
                android:textSize="12sp" />

            <TextView
                android:id="@+id/native_ad_body"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:ellipsize="end"
                android:gravity="center_vertical"
                android:lines="2"
                android:textColor="@android:color/black"
                android:textSize="12sp" />

        </LinearLayout>

        <Button
            android:id="@+id/native_ad_call_to_action"
            android:layout_width="100dp"
            android:layout_height="30dp"
            android:layout_gravity="center_vertical"
            android:layout_weight="1"
            android:background="#4286F4"
            android:paddingLeft="3dp"
            android:paddingRight="3dp"
            android:textColor="@android:color/white"
            android:textSize="12sp"
            android:visibility="gone" />

    </LinearLayout>

</LinearLayout>

Etapa 3: preencher o layout com os metadados do anúncio

Cenário 1: exibir imediatamente o anúncio após o carregamento. Modifique o método onAdLoaded() acima para recuperar as propriedades de Native Ad's e exibir da seguinte forma:

private NativeAdLayout nativeAdLayout;
private LinearLayout adView;
private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd object. 
    // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
    // now, while you are testing and replace it later when you have signed up.
    // While you are using this temporary code you will only get test ads and if you release
    // your code like this to the Google Play your users will not receive ads (you will get a no fill error).
    nativeAd = new NativeAd(this, "YOUR_PLACEMENT_ID");

    NativeAdListener nativeAdListener = new NativeAdListener() {
        ...
        @Override
        public void onAdLoaded(Ad ad) {
            // Race condition, load() called again before last ad was displayed
            if (nativeAd == null || nativeAd != ad) {
                return;
            }
            // Inflate Native Ad into Container
            inflateAd(nativeAd);
        }
        ...
    };

    // Request an ad
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .build());
}

private void inflateAd(NativeAd nativeAd) {

    nativeAd.unregisterView();

    // Add the Ad view into the ad container.
    nativeAdLayout = findViewById(R.id.native_ad_container);
    LayoutInflater inflater = LayoutInflater.from(NativeAdActivity.this);
    // Inflate the Ad view.  The layout referenced should be the one you created in the last step.
    adView = (LinearLayout) inflater.inflate(R.layout.native_ad_layout_1, nativeAdLayout, false);
    nativeAdLayout.addView(adView);

    // Add the AdOptionsView
    LinearLayout adChoicesContainer = findViewById(R.id.ad_choices_container);
    AdOptionsView adOptionsView = new AdOptionsView(NativeAdActivity.this, nativeAd, nativeAdLayout);
    adChoicesContainer.removeAllViews();
    adChoicesContainer.addView(adOptionsView, 0);

    // Create native UI using the ad metadata.
    MediaView nativeAdIcon = adView.findViewById(R.id.native_ad_icon);
    TextView nativeAdTitle = adView.findViewById(R.id.native_ad_title);
    MediaView nativeAdMedia = adView.findViewById(R.id.native_ad_media);
    TextView nativeAdSocialContext = adView.findViewById(R.id.native_ad_social_context);
    TextView nativeAdBody = adView.findViewById(R.id.native_ad_body);
    TextView sponsoredLabel = adView.findViewById(R.id.native_ad_sponsored_label);
    Button nativeAdCallToAction = adView.findViewById(R.id.native_ad_call_to_action);

    // Set the Text.
    nativeAdTitle.setText(nativeAd.getAdvertiserName());
    nativeAdBody.setText(nativeAd.getAdBodyText());
    nativeAdSocialContext.setText(nativeAd.getAdSocialContext());
    nativeAdCallToAction.setVisibility(nativeAd.hasCallToAction() ? View.VISIBLE : View.INVISIBLE);
    nativeAdCallToAction.setText(nativeAd.getAdCallToAction());
    sponsoredLabel.setText(nativeAd.getSponsoredTranslation());

    // Create a list of clickable views
    List<View> clickableViews = new ArrayList<>();
    clickableViews.add(nativeAdTitle);
    clickableViews.add(nativeAdCallToAction);

    // Register the Title and CTA button to listen for clicks.
    nativeAd.registerViewForInteraction(
            adView, nativeAdMedia, nativeAdIcon, clickableViews);
}

O SDK registrará a impressão e controlará o clique automaticamente. Observe que é necessário registrar a visualização do anúncio com a instância NativeAd para permitir isso. Para tornar todos os elementos da visualização clicáveis, registre-a usando:

registerViewForInteraction(View view, MediaView adMediaView, MediaView adIconView)

Ao usar o registerViewForInteraction com NativeAds, o SDK verifica se a chamada está em execução no thread principal para evitar condições de corrida. Executamos as nossas verificações com Preconditions.checkIsOnMainThread(). Verifique se a implementação está de acordo com o padrão, pois o aplicativo falhará se fizer uma chamada para registoViewForInteraction a partir de um thread em segundo plano.

Cenário 2: exibir o anúncio poucos segundos ou minutos após o carregamento. Você deve verificar se o anúncio foi invalidado antes de exibi-lo.

Caso o anúncio não seja exibido imediatamente depois de carregado, o desenvolvedor será responsável por verificar se o anúncio foi invalidado. Quando o anúncio for carregado com sucesso, ele será válido por 60 min. Você não será pago se estiver exibindo um anúncio invalidado. Chame isAdInvalidated() para validar o anúncio.

É necessário seguir a ideia abaixo, mas não copie o código para o seu projeto, pois este é apenas um exemplo:

private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd object. 
    // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
    // now, while you are testing and replace it later when you have signed up.
    // While you are using this temporary code you will only get test ads and if you release
    // your code like this to the Google Play your users will not receive ads (you will get a no fill error).
    nativeAd = new NativeAd(this, "YOUR_PLACEMENT_ID");

    NativeAdListener nativeAdListener = new NativeAdListener() {
        ...
    };

    // Request an ad
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .build());

    // Here is just an example for displaying the ad with delay
    // Please call this method at appropriate timing in your project
    showNativeAdWithDelay();
}

private void showNativeAdWithDelay() {
    /**
     * Here is an example for displaying the ad with delay;
     * Please do not copy the Handler into your project
     */
    Handler handler = new Handler();
    handler.postDelayed(new Runnable() {
        public void run() {
            // Check if nativeAd has been loaded successfully
            if(nativeAd == null || !nativeAd.isAdLoaded()) {
                return;
            }
            // Check if ad is already expired or invalidated, and do not show ad if that is the case. You will not get paid to show an invalidated ad.
            if(nativeAd.isAdInvalidated()) {
                return;
            }
            inflateAd(nativeAd); // Inflate NativeAd into a container, same as in previous code examples
        }
    }, 1000 * 60 * 15); // Show the ad after 15 minutes
}

Como controlar a área clicável

Para uma melhor experiência de usuário e melhores resultados, sempre considere a possibilidade de controlar a área clicável do seu anúncio para evitar cliques involuntários. Consulte a página da Política do SDK do Audience Network para obter mais detalhes sobre a aplicação de espaço em branco não clicável.

Para ter maior controle sobre o que pode ser clicado, use o método registerViewForInteraction(View view, MediaView adMediaView, MediaView adIconView, List<View> clickableViews) para registrar uma lista de visualizações que podem ser clicadas. Por exemplo, se quiser tornar apenas o título do anúncio e o botão de chamada para ação clicáveis, no exemplo anterior, será possível escrever assim:

@Override
public void onAdLoaded(Ad ad) {
    ...
    // Create a list of clickable views
    List<View> clickableViews = new ArrayList<>();
    clickableViews.add(nativeAdTitle);
    clickableViews.add(nativeAdCallToAction);

    // Register the Title and CTA button to listen for clicks.
    nativeAd.registerViewForInteraction(
            adView, nativeAdMedia, nativeAdIcon, clickableViews);
    ...
}

Em casos nos quais a visualização é reutilizada para exibir anúncios diferentes ao longo do tempo, faça uma chamada para unregisterView() antes de registrar a mesma visualização com uma instância diferente de NativeAd.

Execute o código e verá um anúncio nativo:

Etapa 4: usar o MediaView

Para exibir a imagem da capa do anúncio nativo, é obrigatório usar o MediaView do Audience Network da Meta que mostra ativos de imagem e vídeo. Confira as diretrizes para unidades de anúncio de vídeo nativo aqui.

Por padrão, os ativos de imagem e vídeo são pré-armazenados em cache ao carregar anúncios nativos. Com isso, o MediaView pode reproduzir vídeos logo após o carregamento de nativeAd.

private void loadNativeAd() {
    ...
    nativeAd.loadAd();
}

Além disso, é possível especificar NativeAd.MediaCacheFlag.ALL explicitamente ao carregar anúncios nativos.

private void loadNativeAd() {
    ...
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withMediaCacheFlag(NativeAdBase.MediaCacheFlag.ALL)
                    .build());
}

O Audience Network aceita duas opções de cache em anúncios nativos, conforme definido no enum NativeAd.MediaCacheFlag:

Constantes do cache Descrição

ALL

Pré-armazenamento de tudo (ícone, imagens e vídeo) no cache, padrão

NONE

Sem pré-armazenamento no cache

Quando um anúncio for carregado, as seguintes propriedades incluirão algum valor: title, icon, coverImage e callToAction. Outras propriedades podem ser nulas ou estar vazias. Certifique-se de que se seu código é sólido o suficiente para lidar com esses casos.

Se não houver nenhum anúncio para exibir, onError receberá uma chamada com um error.code. Se você usa o próprio relatório personalizado ou camada de mediação, verifique o valor do código para detectar esse caso. Nesse caso, você pode recorrer a uma rede de anúncios alternativa. Não solicite novamente um anúncio logo em seguida.

Os metadados de anúncios que você recebe podem ser armazenados em cache e reutilizados por até 1 hora. Se você pretende usar os metadados após esse período, faça uma chamada para carregar um novo anúncio.

Etapa 5: carregar o anúncio sem cache automático

  • Recomendamos manter o armazenamento de mídia no cache ativado por padrão em todos os casos. Entretanto, permitimos a substituição do padrão usando MediaCacheFlag.NONE no método loadAd. Tome muito cuidado se optar por substituir o padrão de armazenamento das mídias no cache.
private final String TAG = NativeAdActivity.class.getSimpleName();
private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd object. 
    // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
    // now, while you are testing and replace it later when you have signed up.
    // While you are using this temporary code you will only get test ads and if you release
    // your code like this to the Google Play your users will not receive ads (you will get a no fill error).
    nativeAd = new NativeAd(this, "YOUR_PLACEMENT_ID");
    NativeAdListener nativeAdListener = new NativeAdListener() {
        ...
    };

    // Request an ad without auto cache
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .withMediaCacheFlag(NativeAdBase.MediaCacheFlag.NONE)
                    .build());
}
  • Depois de invocar onAdLoaded com sucesso no anúncio, é possível fazer uma chamada para o método downloadMedia a fim de começar a baixar todas as mídias do anúncio nativo quando apropriado.
@Override
public void onAdLoaded(Ad ad) {
    if (nativeAd == null || nativeAd != ad) {
        return;
    }

    nativeAd.downloadMedia();
}
  • Por fim, é possível fazer uma chamada para o método registerViewForInteraction e exibir o anúncio após o carregamento da mídia no retorno de chamada onMediaDownloaded.
@Override
public void onMediaDownloaded(Ad ad) {
    if (nativeAd == null || nativeAd != ad) {
        return;
    }

    inflateAd(nativeAd); // Inflate NativeAd into a container, same as in previous code examples
}

Se você carregou o anúncio sem cache automático e não fez uma chamada para iniciar o download por downloadMedia, a mídia só será baixada quando registerViewForInteraction for chamado. Toda a mídia precisa ser baixada e exibida para qualificar uma impressão.

Aceleração de hardware para anúncios de vídeo

Os anúncios de vídeo no Audience Network exigem a ativação da exibição com aceleração de hardware, ou poderá haver uma tela preta na visualizações de vídeo. Isso se aplica a

  • Criativos de vídeo em anúncios nativos
  • Criativos de vídeo em anúncios intersticiais
  • Anúncios de vídeo in-stream
  • Vídeos com incentivo

A aceleração de hardware será ativada por padrão se o nível da sua API de destino for >=14 (Ice Cream Sandwich, Android 4.0.1), mas você pode também ativar esse recurso de forma explícita no nível de aplicativo ou no nível de atividade.

Nível de aplicativo

No arquivo de manifesto do Android, adicione o seguinte atributo à tag <application> para ativar a aceleração de hardware no aplicativo inteiro:

<application android:hardwareAccelerated="true" ...>

Nível de atividade

Caso você queira ativar o recurso somente para atividades específicas do seu aplicativo, no arquivo de manifesto do Android, é possível adicionar o seguinte recurso à tag <activity>. O exemplo a seguir ativará a aceleração de hardware de AudienceNetworkActivity, que é usada para renderizar anúncios intersticiais e vídeos com incentivo:

<activity android:name="com.facebook.ads.AudienceNetworkActivity" android:hardwareAccelerated="true" .../>

Próximas etapas

  • Consulte o guia Modelo de anúncio nativo para adicionar anúncios nativos ao aplicativo.

  • Explore os nossos exemplos de código que mostram como usar anúncios nativos. NativeAdSample está disponível como parte do SDK. É possível encontrar o modelo na pasta AudienceNetwork/samples. Importe o projeto para o seu IDE e execute-o em um dispositivo ou no emulador.

Mais recursos

Guia de introdução

Guia técnico de introdução ao Audience Network

Exemplos de código

Amostras de integração de anúncios do Audience Network

Perguntas frequentes

Perguntas frequentes sobre o Audience Network

Modelo de anúncios nativos

Uma abordagem mais indireta em relação à integração de anúncios nativos