在 Android 應用程式中加入原生廣告

您可以使用原生廣告 API 自行設計想要的應用程式廣告，打造出最符合需求的廣告體驗。原生廣告 API 不會直接提供可立即刊登的廣告，而是提供標題、圖像、行動呼籲等眾多廣告屬性，讓您使用這些屬性自行建構用以顯示廣告的自訂檢視。

繼續操作前，請務必詳閱 Audience Network 新手指南與 Android 新手指南。

在本指南中，我們將實作下列原生廣告版位。您可以使用以下元件建立原生廣告：

檢視 #1：廣告圖示

檢視 #2：廣告標題

檢視 #3：贊助標籤

檢視 #4：AdOptionsView

檢視 #5：MediaView

檢視 #6：社交元素

檢視 #7：廣告內文

檢視 #8：行動呼籲按鈕

原生廣告步驟

步驟 1：要求使用原生廣告

步驟 2：建立原生廣告版面配置

步驟 3：使用廣告的中繼資料產生版面

步驟 4：使用 MediaView

步驟 5：載入廣告，不自動快取

初始化 Audience Network SDK

Android Audience Network SDK 5.1 版本已新增此方法。

自 5.3.0 及以上版本起，必須明確初始化 Audience Network Android SDK。請參閱本文件瞭解如何初始化 Audience Network Android SDK。

在建立廣告物件或載入廣告之前，應初始化 Audience Network SDK。建議在應用程式啟動時使用此方法。

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

步驟 1：要求使用原生廣告

在 Activity 最上方加入下列程式碼，以匯入 Facebook 廣告 SDK：

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 的版面 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：廣告成功載入幾秒或幾分鐘後顯示。您應該在顯示廣告之前檢查廣告是否已失效。

如果廣告載入之後沒有立即顯示，開發人員有責任檢查廣告是否已失效。廣告載入成功後，有效期為 60 分鐘。如果顯示的是已失效的廣告，您將無法獲得付款。您應呼叫 isAdInvalidated() 來驗證廣告。

您應該遵循以下構思，但請不要將程式碼複製到您的專案中，因為這只是範例：

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
}

控制可點擊範圍

為了提供更出色的用戶體驗以及獲得更卓越的成果，強烈建議您控制廣告的可點擊範圍，以免用戶誤點廣告。若要深入瞭解不可點擊的空白區域規定，請參閱 Audience Network SDK 政策頁面。

為了更精確地控制可點擊範圍，您可以使用 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

若要顯示原生廣告封面圖像，您必須使用可同時顯示圖像和影片素材的 Meta Audience Network MediaView。您可以在這裡查看原生影片廣告單位的設計原則。

根據預設，載入原生廣告時，會將圖像和影片素材全部預先快取，讓 MediaView 能夠在 nativeAd 完成載入時立即播放影片。

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

此外，您也可以在載入原生廣告時，明確指定 NativeAd.MediaCacheFlag.ALL。

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

Audience Network 支援兩種原生廣告快取選項，如 NativeAd.MediaCacheFlag 列舉值所定義：

快取常數	說明
`ALL`	全部預先快取（圖示、圖像和影片）（預設值）
`NONE`	不預先快取

廣告載入時，下列屬性會包含某值：title、icon、coverImage 和 callToAction。其他屬性則可能是 Null 或空白。請確定程式碼在處理這些情況時是否面面俱到。

若無廣告可顯示，程式會呼叫 onError 並顯示 error.code。如果您使用自己的自訂分析報告或中介服務層，可以檢查錯誤代碼值，並偵測此狀況。您可在發生此狀況時以其他廣告聯播網作為後援，但請勿隨後立即重新要求廣告。

系統可以快取您接收到的廣告中繼資料，並重複使用長達 1 小時。如果您計畫在此時段後使用中繼資料，請發出呼叫以載入新的廣告。

步驟 5：載入廣告，不自動快取

強烈建議您無論在何種情況下，皆預設開啟影音素材快取。不過，您可以在 loadAd 方法中使用 MediaCacheFlag.NONE 來覆寫預設值。若您決定要覆寫我們預設的影音素材快取設定，請務必謹慎操作。

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 時才會開始下載影音素材。所有影音素材都必須載入並顯示，才能符合曝光的資格。

針對影片廣告的硬體加速

Audience Network 中的影片廣告必須啟用硬體加速顯示，否則觀看影片時可能會出現畫面變黑的情況。適用項目

原生廣告中的影片廣告創意
插頁廣告中的影片廣告創意
插播影片廣告
獎勵式影片

如果目標 API 層級 >=14（Ice Cream Sandwich，Android 4.0.1），預設會啟用硬體加速，但也可在應用程式層級或活動層級明確啟用這個功能。

應用程式層級

在 Android Manifest 檔案中，將以下屬性加入 <application> 標籤，即可啟用整個應用程式的硬體加速：

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

活動層級

如果只想針對應用程式中的特定活動啟用這個功能，可以在 Android Manifest 檔案中將以下功能加入 <activity> 標籤。以下範例會針對 AudienceNetworkActivity 啟用硬體加速，這是用於顯示插頁廣告和獎勵式影片：

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

後續步驟

若要在您的應用程式中整合不同的廣告格式，請依照指南操作：

參考 Github 上的 Audience Network Android 程式碼範例，將專案匯入到您的整合開發環境（IDE），然後在裝置或模擬器上執行。
當您準備好讓應用程式正式上線並開始營利，請確保您的應用程式並未違反 Audience Network 政策與 Facebook 社群守則，接著便可以將應用程式送審。

參閱原生廣告範本指南，將原生廣告加入您的應用程式中。
探索程式碼範例，瞭解如何使用原生廣告。SDK 的 AudienceNetwork/samples 資料夾中有提供 NativeAdSample。請將該專案匯入您的 IDE，並在裝置或模擬器上執行。

在 Android 應用程式中加入原生廣告

檢視 #1：廣告圖示

檢視 #2：廣告標題

檢視 #3：贊助標籤

檢視 #4：AdOptionsView

檢視 #5：MediaView

檢視 #6：社交元素

檢視 #7：廣告內文

檢視 #8：行動呼籲按鈕

原生廣告步驟

步驟 1：要求使用原生廣告

步驟 2：建立原生廣告版面配置

步驟 3：使用廣告的中繼資料產生版面

步驟 4：使用 MediaView

步驟 5：載入廣告，不自動快取

初始化 Audience Network SDK

步驟 1：要求使用原生廣告

步驟 2：建立原生廣告版面配置

步驟 3：使用廣告的中繼資料產生版面

案例 1：廣告成功載入後立即顯示。修改上面的 `onAdLoaded()` 方法，以擷取 `Native Ad's` 屬性並顯示如下：

案例 2：廣告成功載入幾秒或幾分鐘後顯示。您應該在顯示廣告之前檢查廣告是否已失效。

控制可點擊範圍

步驟 4：使用 MediaView

步驟 5：載入廣告，不自動快取

針對影片廣告的硬體加速

應用程式層級

活動層級

後續步驟

其他資源

新手指南

程式碼範例

常見問題

原生廣告範本

在 Android 應用程式中加入原生廣告

檢視 #1：廣告圖示

檢視 #2：廣告標題

檢視 #3：贊助標籤

檢視 #4：AdOptionsView

檢視 #5：MediaView

檢視 #6：社交元素

檢視 #7：廣告內文

檢視 #8：行動呼籲按鈕

原生廣告步驟

初始化 Audience Network SDK

步驟 1：要求使用原生廣告

步驟 2：建立原生廣告版面配置

步驟 3：使用廣告的中繼資料產生版面

案例 1：廣告成功載入後立即顯示。修改上面的 onAdLoaded() 方法，以擷取 Native Ad's 屬性並顯示如下：

案例 2：廣告成功載入幾秒或幾分鐘後顯示。您應該在顯示廣告之前檢查廣告是否已失效。

控制可點擊範圍

步驟 4：使用 MediaView

步驟 5：載入廣告，不自動快取

針對影片廣告的硬體加速

應用程式層級

活動層級

後續步驟

其他資源

案例 1：廣告成功載入後立即顯示。修改上面的 `onAdLoaded()` 方法，以擷取 `Native Ad's` 屬性並顯示如下：