Meta Audience Network

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

原生橫額廣告 API 可讓您打造顯示原生廣告的自訂體驗，而無需使用廣告客戶的廣告創意素材，例如圖片、影片或輪播廣告內容。與原生廣告相似，您將收到一組廣告屬性（如標題、圖示、呼籲字句），並會使用這些廣告屬性來建立用於展示廣告的自訂檢視畫面。但與橫額廣告不同的是，原生橫額廣告 API 提供原生版面體驗，讓您可以完全控制要如何自訂廣告內的元件版面。

確保您在開始操作前，已經先行參閱 Audience Network 新手指南及 Android 新手指南。

在本指南中，我們會安裝以下原生橫額廣告版位。您會使用下列元件建立原生橫額廣告：

檢視內容 #1：廣告選項檢視

檢視內容 #2：贊助標籤

檢視內容 #3：廣告圖示

檢視內容 #4：廣告標題

檢視內容 #5：社交元素

檢視內容 #6：呼籲字句按鈕




原生橫額廣告步驟

第 1 步：要求原生橫額廣告

第 2 步：建立原生橫額廣告版面

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

為 Audience Network SDK 執行初始化

Android Audience Network SDK 5.1 版已加入此方法。

若是 5.3.0 或更高版本，您必須初始化 Android 版 Audience Network SDK如欲了解有關初始化 Android 版 Audience Network SDK 的方法，請參閱此文件。

在建立廣告物件及載入廣告前，請為 Audience Network SDK 執行初始化。我們建議您在啟動應用程式時執行此動作。

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

第 1 步：要求原生橫額廣告

在「活動」頂端加入下列代碼，以匯入 Facebook 廣告 SDK：

import com.facebook.ads.*;

然後將 NativeBannerAd 物件實例化，建立一個 AdListener，並在動態中呼叫 loadAd()：

public class NativeBannerAdActivity extends Activity {

    private final String TAG = NativeBannerAdActivity.class.getSimpleName();
    private NativeBannerAd nativeBannerAd;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Instantiate a NativeBannerAd 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).
        nativeBannerAd = new NativeBannerAd(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!");
            }
        });
        // load the ad
        nativeBannerAd.loadAd(
                nativeBannerAd.buildLoadAdConfig()
                        .withAdListener(nativeAdListener)
                        .build());
    }
}

我們稍後將回到這個步驟，將程式碼加入 onAdLoaded() 方法。

第 2 步：建立原生橫額廣告版面

下一步是擷取廣告中繼資料，然後使用其屬性來建立自訂的原生 UI。您可在版面 .xml 中建立自訂視圖，或在代碼中加入元素。

設計應用程式中的原生橫額廣告時，請參閱原生廣告指南。

在您的動態版面 activity_main.xml 中，為您的原生橫額廣告新增容器。該容器應該為 com.facebook.ads.NativeAdLayou，它是 FrameLayout 頂部的一個封裝程式，具備一些額外的功能，使我們能夠在廣告上方顯示原生廣告報告流程。然後，在 onAdLoaded() 方法中，您將需要將原生廣告檢視畫面加入該容器內。

<?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">
    ...
    <com.facebook.ads.NativeAdLayout
        android:id="@+id/native_banner_ad_container"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_alignParentBottom="true" />
    ...
</RelativeLayout>

為原生橫額廣告建立自訂版面 native_banner_ad_unit.xml：



下方為原生橫額廣告的自訂版面範例：

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="vertical">

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

        <RelativeLayout
            android:id="@+id/ad_choices_container"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:padding="2dp" />

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

    <RelativeLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:background="@android:color/white">

        <com.facebook.ads.MediaView
            android:id="@+id/native_icon_view"
            android:layout_width="50dp"
            android:layout_height="50dp"
            android:layout_alignParentLeft="true"
            android:layout_alignParentStart="true"
            android:gravity="center" />

        <LinearLayout
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:layout_centerVertical="true"
            android:orientation="vertical"
            android:paddingLeft="53dp"
            android:paddingRight="83dp">

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

            <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:textSize="12sp" />
        </LinearLayout>

        <Button
            android:id="@+id/native_ad_call_to_action"
            android:layout_width="80dp"
            android:layout_height="50dp"
            android:layout_alignParentEnd="true"
            android:layout_alignParentRight="true"
            android:background="#4286F4"
            android:gravity="center"
            android:paddingLeft="3dp"
            android:paddingRight="3dp"
            android:textColor="@android:color/white"
            android:textSize="12sp"
            android:visibility="gone" />

    </RelativeLayout>
</LinearLayout>

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

情境 1：在廣告成功載入後立即顯示廣告。修改上方的 onAdLoaded() 方法以擷取 Native Banner Ad's 屬性，並以下列方式顯示廣告：

public class NativeBannerAdActivity extends Activity {

    private NativeAdLayout nativeAdLayout;
    private LinearLayout adView;
    private NativeBannerAd nativeBannerAd;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Instantiate a NativeBannerAd 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).
        nativeBannerAd = new NativeBannerAd(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 (nativeBannerAd == null || nativeBannerAd != ad) {
                    return;
                 }
                // Inflate Native Banner Ad into Container
                inflateAd(nativeBannerAd);
            }
            ...
        });
        // load the ad
        nativeBannerAd.loadAd(
                nativeBannerAd.buildLoadAdConfig()
                        .withAdListener(nativeAdListener)
                        .build());
    }

    private void inflateAd(NativeBannerAd nativeBannerAd) {
        // Unregister last ad
        nativeBannerAd.unregisterView();

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

        // Add the AdChoices icon
        RelativeLayout adChoicesContainer = adView.findViewById(R.id.ad_choices_container);
        AdOptionsView adOptionsView = new AdOptionsView(NativeBannerAdActivity.this, nativeBannerAd, nativeAdLayout);
        adChoicesContainer.removeAllViews();
        adChoicesContainer.addView(adOptionsView, 0);

        // Create native UI using the ad metadata.
        TextView nativeAdTitle = adView.findViewById(R.id.native_ad_title);
        TextView nativeAdSocialContext = adView.findViewById(R.id.native_ad_social_context);
        TextView sponsoredLabel = adView.findViewById(R.id.native_ad_sponsored_label);
        MediaView nativeAdIconView = adView.findViewById(R.id.native_icon_view);
        Button nativeAdCallToAction = adView.findViewById(R.id.native_ad_call_to_action);

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

        // Register the Title and CTA button to listen for clicks.
        List<View> clickableViews = new ArrayList<>();
        clickableViews.add(nativeAdTitle);
        clickableViews.add(nativeAdCallToAction);
        nativeBannerAd.registerViewForInteraction(adView, nativeAdIconView, clickableViews);
    }
}

SDK 會自動記錄展示次數並處理點擊。請注意，您必須使用 NativeBannerAd 實例註冊廣告檢視畫面，才能啟用檢視畫面。若要將視圖的所有廣告元素設為可點擊，請使用下列項目註冊該視圖：

registerViewForInteraction(View view, MediaView adIconView)

情境 2：在廣告成功載入幾秒或幾分鐘過後顯示廣告。顯示廣告前，您應檢查廣告是否已經無效。

如果廣告在載入後沒有立即顯示，開發人員就需要檢查廣告是否已經無效。成功載入後，廣告的有效期為 60 分鐘。如果您顯示了無效廣告，就無法收取款項。請調用 isAdInvalidated() 以驗證廣告。

您應該參考下列思路操作，但是請不要將以下程式碼複製到您的專案中，因為這只是一個範例：

public class NativeBannerAdActivity extends Activity {

    private NativeBannerAd nativeBannerAd;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Instantiate a NativeBannerAd 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).
        nativeBannerAd = new NativeBannerAd(this, "YOUR_PLACEMENT_ID");
         NativeAdListener nativeAdListener = new NativeAdListener() {
            ...
        });
        // load the ad
        nativeBannerAd.loadAd(
                nativeBannerAd.buildLoadAdConfig()
                        .withAdListener(nativeAdListener)
                        .build());
    }

    private void showAdWithDelay() {
       /**
        * 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 nativeBannerAd has been loaded successfully
               if(nativeBannerAd == null || !nativeBannerAd.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(nativeBannerAd.isAdInvalidated()) {
                   return;
               }
               inflateAd(nativeBannerAd); // Inflate Native Banner Ad into Container same as in previous code example
           }
       }, 1000 * 60 * 15); // Show the ad after 15 minutes
    }
}

控制可點擊的區域

為了提供更優質的用戶體驗及更卓越的成效，您應時常考慮控制廣告中可點擊的區域，以避免發生用戶意外點擊的情況。若要進一步瞭解空白處不可點擊的相關規定，請參閱 Audience Network SDK 政策頁面。

若要有效控制哪些內容可供點擊，您可以使用 registerViewForInteraction(View view, MediaView adIconView, List<View> clickableViews) 來註冊可點擊的檢視畫面清單。舉例來說，如果您只希望前面範例中的廣告標題和呼籲字句按鈕可以點擊，則可編寫如下代碼：

@Override
public void onAdLoaded(Ad ad) {
  ...
  List<View> clickableViews = new ArrayList<>();
  clickableViews.add(nativeAdTitle);
  clickableViews.add(nativeAdCallToAction);
  nativeBannerAd.registerViewForInteraction(mAdView, nativeAdIconView, clickableViews);
  ...
}

若要重複使用檢視畫面以便在不同時間顯示不同廣告，則必須先呼叫 unregisterView()，然後再使用不同的 NativeBannerAd 實例來註冊同一檢視畫面。

執行代碼後，您應該就可以看到原生橫額廣告：

載入廣告時，下列屬性會包含部分的值：title、icon 和 callToAction。其他屬性會是 Null 或空白。請確定您的程式碼是否足以處理這些情況。


若無廣告可顯示，系統會呼叫 onError 並顯示 error.code。如使用您自訂的回報或中介層，最好檢查錯誤代碼值，以偵測此狀況。您可在發生此狀況時以其他廣告聯盟作為後援，但請勿之後立即重新要求廣告。


您可快取接收到的廣告中繼資料，並重複使用長達 30 分鐘若在此時間後才想要使用中繼資料，就必須調用載入新廣告。

後續步驟

  • 請參閱原生廣告範例指南，了解如何在應用程式中加入原生廣告。

  • 探索代碼範例，了解如何使用原生廣告。NativeBannerAdSample 包含在 SDK 中，您可在 AudienceNetwork/samples 資料夾中找到有關資料。將該專案匯入到您的整合開發環境（IDE），然後在裝置或模擬器上執行。

更多資源

新手指南

Audience Network 入門技術指南

程式碼範例

Audience Network 廣告整合範例

常見問題

Audience Network 常見問題

原生廣告範本

這是個較為輕鬆的原生廣告整合方法