Добавление нативной рекламы в приложение для Android

С помощью API Native Ad вы можете создавать индивидуально настроенную рекламу для своего приложения. Выбирая API Native Ad вместо готовой к показу рекламы, вы получаете набор свойств рекламы (название, изображение, призыв к действию и т. п.), позволяющих разработать для нее индивидуальное представление.

Из этого руководства вы узнаете, как реализовать размещение нативной рекламы. Вы создадите нативную рекламу со следующими компонентами:

Создание нативной рекламы

Шаг 1. Запрос нативной рекламы

Шаг 2. Создание компоновки нативной рекламы

Шаг 3. Заполнение компоновки метаданными рекламы

Шаг 4. Использование MediaView

Шаг 5. Загрузка рекламы без автоматического кэширования

Шаг 1. Запрос нативной рекламы

Чтобы импортировать SDK Facebook Ads, добавьте в начало действия следующий код:

import com.facebook.ads.*;

Затем создайте экземпляр объекта NativeAd, задайте NativeAdListener и вызовите loadAd() с использованием слушателя рекламы:

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

Позднее мы вернемся к этому шагу и добавим код метода onAdLoaded().

Шаг 2. Создание компоновки нативной рекламы

Следующий шаг — получение метаданных рекламы и использование ее свойств для создания пользовательского нативного интерфейса. Вы можете создать индивидуальное представление в XML-файле компоновки или добавить элементы в код.

В компоновку действия activity_main.xml добавьте контейнер для Native Ad. Контейнер должен представлять собой com.facebook.ads.NativeAdLayout, то есть оболочку FrameLayout с дополнительными функциями, которые позволяют нам отображать нативный поток отчетов о рекламе поверх объявлений.

<?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>

Создайте для нативной рекламы пользовательскую компоновку native_ad_layout.xml:

Ниже приведен пример пользовательской компоновки для нативной рекламы:

<?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>

Шаг 3. Заполнение компоновки метаданными рекламы

Сценарий 1. Немедленное отображение объявления после загрузки. Измените показанный выше метод onAdLoaded() таким образом, чтобы он извлекал свойства Native Ad's и показывал рекламу:

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

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

registerViewForInteraction(View view, MediaView adMediaView, MediaView adIconView)

Когда используется registerViewForInteraction с NativeAds, SDK проверяет, запущен ли вызов из главного потока — это необходимо, чтобы избежать состояния гонки. Проверка выполняется с помощью Preconditions.checkIsOnMainThread(). Ваша реализация должна соответствовать этому стандарту, поскольку при попытке вызвать registerViewForInteraction из фонового потока произойдет сбой приложения.

Сценарий 2. Отображение объявления через несколько секунд или минут после загрузки. Прежде чем показывать объявление, необходимо проверить, не было ли оно признано недействительным.

Следуйте идее ниже, но не копируйте код в свой проект, так как это всего лишь пример:

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
}

Управление интерактивной областью

Чтобы уточнить интерактивную область, с помощью registerViewForInteraction(View view, MediaView adMediaView, MediaView adIconView, List<View> clickableViews) зарегистрируйте список представлений, которые можно нажимать. Например, чтобы в предыдущем примере сделать интерактивными только заголовок рекламы и кнопку призыва к действию, нужно использовать следующий код:

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

Если представление будет использоваться для показа других рекламных объявлений, вызовите unregisterView() перед регистрацией того же самого представления для другого экземпляра NativeAd.

Выполните код, и вы увидите нативную рекламу:

Шаг 4. Использование MediaView

Для отображения обложки нативной рекламы обязательно использовать класс MediaView Meta Audience Network, который может отображать как изображения, так и видео. Наши рекомендации по оформлению нативной видеорекламы см. здесь.

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

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

Кроме того, при загрузке нативной рекламы можно явным образом указать NativeAd.MediaCacheFlag.ALL.

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

Audience Network поддерживает два варианта кэширования в нативной рекламе, как задано в объекте enum NativeAd.MediaCacheFlag:

Шаг 5. Загрузка рекламы без автоматического кэширования

• Настоятельно рекомендуется по умолчанию никогда не выключать кэширование медиафайлов. Однако при необходимости этот параметр по умолчанию можно переопределить с помощью MediaCacheFlag.NONE в методе loadAd. Будьте очень осторожны, если решите изменить параметры кэширования медиафайлов, установленные по умолчанию.

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

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

@Override
public void onAdLoaded(Ad ad) {
    if (nativeAd == null || nativeAd != ad) {
        return;
    }

    nativeAd.downloadMedia();
}

• Наконец, можно вызвать метод registerViewForInteraction и показать рекламу после завершения ее загрузки в обратном вызове 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
}

Если вы загрузили рекламу без автоматического кэширования и не вызывали downloadMedia вручную для начала скачивания, загрузка медиаматериалов начнется только при вызове registerViewForInteraction. Чтобы показ был засчитан, должны быть загружены и отображены все медиаматериалы.

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

• Изучите наши примеры кода, демонстрирующие способы использования нативной рекламы. NativeAdSample является частью SDK и находится в папке AudienceNetwork/samples. Импортируйте проект в свою интегрированную среду разработки и запустите его на устройстве или в эмуляторе.