Android 專用 AdSense 行動應用程式搜尋廣告 (AFSMA) 導入作業

必要條件

本實作指南假設您已熟悉下列項目：

  • AFS 自訂搜尋廣告 (CSA) 導入通訊協定
  • Android 應用程式開發
  • 將 Android 版 (現已成為 Google Play 服務) 的 Google Mobile Ads SDK 與 Android Studio 專案建立關聯。必須安裝 9.0.0 版的 Google Play 服務。

類別

如要在應用程式中放送 AFSMA 廣告 (也稱為動態高度搜尋廣告)，請實作下列類別：

SearchAdView

  • 這個類別繼承自 Android ViewGroup 類別，並顯示 AFSMA 廣告。SearchAdView 使用 DynamicHeightSearchAdRequest 發出廣告請求，並顯示傳回的廣告。請將 SearchAdView 新增至應用程式的任何現有檢視區塊群組。
  • SearchAdView 必須以 SearchAdView 執行時的結構定義 (通常是 Activity) 進行例項化。
  • SearchAdView 執行個體化後，您必須使用 AdSize.SEARCH 呼叫 setAdSize() 方法，才能要求 AFSMA 廣告。其他列舉值則會請求與行動應用程式專用 AdSense 搜尋廣告不相容的廣告。
  • 使用屬性程式碼呼叫這個物件的 setAdUnitId() 方法。

DynamicHeightSearchAdRequest.Builder

  • 此類別會封裝廣告請求參數。這類似於在 AdSense 搜尋廣告的電腦版和行動版網站中，設定 JavaScript 廣告請求物件 (網頁選項、單元選項) 中的參數。
  • 使用適當的 setter 設定參數 (也就是呼叫 setQuery() 來設定查詢參數)。

導入範例

以下範例說明如何使用 Activity 建立 SearchAdView 做為 ViewGroup 的子檢視畫面。為了正確要求 AFSMA 廣告，SearchAdView 物件必須使用 AdSize.SEARCH 呼叫 setAdSize() 方法。

//  MainActivity.java implementation
//  (MainActivity is a subclass of Activity)

// Create the SearchAdView
final SearchAdView searchAdView = new SearchAdView(this);

// Set parameter to request for dynamic height search ads
searchAdView.setAdSize(AdSize.SEARCH); // Important!

// Replace with your pub ID (e.g. ms-app-pub-9616389000213823)
searchAdView.setAdUnitId("ms-app-pub-################");

// Add searchAdView to parent view group
...

在同一個 Activity 內建立 DynamicHeightSearchAdRequest.Builder，指定將在 SearchAdView 中顯示的廣告參數。AFSMA 廣告的設定方式與 AFS 自訂搜尋廣告相同；詳情請參閱 AdSense 搜尋廣告自訂搜尋廣告參考資料。

// Create the ad request
DynamicHeightSearchAdRequest.Builder builder =
        new DynamicHeightSearchAdRequest.Builder();
builder.setQuery("flowers");
builder.setNumber(2);

// Replace with the ID of a style from your custom search styles
builder.setAdvancedOptionValue("csa_styleId", "0000000001");

// Customization options (set using setters on
// DynamicHeightSearchAdRequest.Builder)
builder.setAdTest(true);

其他可自訂選項，只要在 DynamicHeightSearchAdRequest.Builder 物件上設定額外屬性即可。

如要發出廣告請求，請使用 SearchAdView 物件的 DynamicHeightSearchAdRequest.Builder 物件呼叫 loadAd() 方法：

searchAdView.loadAd(builder.build());

進階選項

大部分的廣告請求參數都可以透過 DynamicHeightSearchAdRequest.Builder 物件的 setter 方法設定。凡是在 DynamicHeightSearchAdRequest.Builder 中沒有 setter 方法的參數，都可以使用 setAdvancedOptionValue() 方法的鍵/值組合進行設定。請參閱 AFS 自訂搜尋廣告參考資料，瞭解可透過 setAdvancedOptionValue() 方法設定的完整設定清單。

金鑰參數前方必須加上「csa_」前置字串，屬性才能正確設定。

// Advanced customization options (set using key-value pair)

// Set a parameter (parameter_name) and its value (parameter_value)
// builder.setAdvancedOptionValue("csa_parameter_name", "parameter_value");

// Example: Show visible URL below description
// (domainLinkAboveDescription: false)
builder.setAdvancedOptionValue("csa_domainLinkAboveDescription", "false");

如果您使用參數的 setter 方法並設定 setAdvancedOptionValue，第二個呼叫會覆寫第一個呼叫的值。

調查錯誤

SearchAdView (此處為 searchAdView) 包含 setAdListener() 方法，可協助您調查錯誤。在同一個 Activity 內：

searchAdView.setAdListener(new AdListener() {
    @Override
    public void onAdLoaded() {
        // Called when an ad is loaded
        super.onAdLoaded();
        Toast.makeText(MainActivity.this, "Ad Loaded",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");
    }

    @Override
    public void onAdOpened() {
        // Called when an ad opens an overlay that covers the screen
        super.onAdOpened();
        Toast.makeText(MainActivity.this, "Ad Opened",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Opened");
    }

    @Override
    public void onAdLeftApplication() {
        // Called when an ad leaves the application
        // (to go to the browser for example)
        super.onAdLeftApplication();
        Toast.makeText(MainActivity.this, "Ad Left Application",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Left Application");
    }

    @Override
    public void onAdFailedToLoad(int errorCode) {
        // Called when an ad request failed
        super.onAdFailedToLoad(errorCode);
        Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode,
                Toast.LENGTH_SHORT).show();
        Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " +
                errorCode);
    }
});

如要瞭解 onAdFailedToLoad() 回呼方法中使用的常數，請參閱 API 參考資料。

為 Google Play 的資料揭露規定做好準備

Google Play 在 2021 年 5 月宣布推出新的「資料安全性」專區，其中列載開發人員提供的揭露聲明，說明應用程式的資料收集、共用和安全性做法。

本頁面可協助您在使用 AdSense 搜尋廣告原生 SDK 時，符合相關資料揭露規定 (使用 AdSense 購物廣告時亦須遵守這項規定)。在這個頁面中，您可以瞭解我們的 SDK 是否會處理使用者資料，以及處理這些資料的方式。

我們將盡可能開誠佈公地提供相關支援，但應用程式開發人員仍須自行判斷如何回覆 Google Play 的「資料安全性」專區表單，以說明其應用程式的使用者資料蒐集、共用和安全性做法。

如何使用這個網頁上的資訊

本頁面僅列出最新版 SDK 蒐集的使用者資料。

為了完成資料揭露聲明，您可以利用 Android 的資料類型指南，協助判斷哪種資料類型最符合所蒐集的資料。此外，在資料揭露聲明中，請務必提及特定應用程式如何共用及使用蒐集到的資料。

SDK 存取及收集的資料類型

包裹：

com.google.android.gms:play-services-afs-native

com.google.ads.afsn

自動蒐集的資料

AFS SDK 會自動收集以下資料。所有資料都會從裝置傳出至 Google，以放送廣告，且所有資料會在傳輸過程中加密。除非應用程式向使用者查詢內容，否則系統不會收集使用者的個人資訊。

資料 收集這類資料的目的如下...
IP 位址 摘要：
  • 詐欺防範、安全性和法規遵循
  • 廣告或行銷
  • 取得大概位置
詳細資料：
IP 位址會用於防範詐欺和濫用行為，以及取得概略的使用者位置。

接著，系統會使用大概位置，確保放送的廣告符合當地法規，並提供與使用者大概地理位置相關的廣告。

應用程式活動
  • 在應用程式中瀏覽及輕觸頁面的動作
  • 應用程式內搜尋記錄
 摘要：
  • 數據分析
  • 詐欺防範、安全性和法規遵循
  • 廣告或行銷
  • 個人化
詳細資料：
您的應用程式提供了使用者的查詢，以便我們傳回與該關鍵字相關的搜尋廣告。我們會評估傳回的廣告觀看和互動 (輕觸) 次數。
診斷 摘要：
  • 數據分析
詳細資料：
SDK 會評估廣告的顯示延遲時間，以便導入及評估產品改善項目。我們也會傳送當機報告/錯誤報告，且有時也會視需要加入其他檢測設備，以瞭解發布者的功能使用情形。
裝置或其他 ID 摘要：
  • 詐欺防範、安全性和法規遵循
  • 廣告或行銷
詳細資料：
裝置 ID 可用於監控詐欺、濫用行為監控及廣告成效評估。