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.

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

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

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.

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.

É 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 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:

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.

• 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.