Meta Audience Network

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

原生橫幅廣告 API 允許您自訂想要顯示的原生廣告，打造出最符合需求的廣告體驗，不需 借助廣告商的圖像、影片或輪播廣告內容等廣告創意素材。與原生廣告類似，您會收到標題、圖示、行動呼籲等眾多廣告屬性，讓您使用這些屬性自行建構出想要的廣告風貌。不過，原生橫幅廣告 API 提供原生版面體驗，因此您對廣告內部元件的版面擁有完整的自訂控制權，這點就與橫幅廣告不同。

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

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

視圖 #1：AdOptionsView

視圖 #2：贊助標籤

視圖 #3：廣告圖示

視圖 #4：廣告標題

視圖 #5：社交元素

視圖 #6：行動呼籲按鈕




原生橫幅廣告步驟

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

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

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

初始化 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.*;

接著執行個體化 NativeBannerAd 物件，建立 AdListener，然後在 Activity 中呼叫 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 的版面 activity_main.xml 中，新增原生橫幅廣告的容器。容器應該是 com.facebook.ads.NativeAdLayout，其為具備一些額外功能位於 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 分鐘。若在此時間後才想要使用中繼資料，就必須呼叫載入新廣告。

後續步驟

  • 參閱原生廣告範本指南，在應用程式加入原生廣告。

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

其他資源

新手指南

開始使用 Audience Network 的技術指南

程式碼範例

Audience Network 廣告整合範例

常見問題

Audience Network 常見問題

原生廣告範本

減少手動設定的原生廣告整合方式