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

必要條件

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

類別

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

SearchAdView

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

DynamicHeightSearchAdRequest.Builder

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

實作範例

以下範例說明如何使用 Activity 建立 SearchAdView 顯示為 ViewGroup 的子檢視畫面。為了正確請求 AdSense 搜尋廣告，請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 廣告的設定方式與 AdSense 搜尋廣告自訂搜尋廣告相同； 查看 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敬上 物件。

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

searchAdView.loadAd(builder.build());

進階選項

大多數的廣告請求參數都可以透過 setter 方法設定 在 DynamicHeightSearchAdRequest.Builder 物件上。 任何不含 setter 方法的參數 您可以使用以下組合的鍵/值組合來設定「DynamicHeightSearchAdRequest.Builder」： setAdvancedOptionValue() 方法。 查看 AdSense 搜尋廣告自訂搜尋廣告 參考資料 即可查看完整的設定清單 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 購物廣告) 時，達成此資料揭露規定的規定。該頁面可讓您瞭解 Google 的 SDK 是否會處理使用者資料，以及如何處理使用者資料。

我們的目標是盡可能開誠佈公地提供支援服務；不過，應用程式開發人員必須全權負責決定如何回覆 Google Play 的「資料安全性」專區表單，說明應用程式的使用者資料收集、共用和安全性做法。

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

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

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

SDK 存取及收集的資料類型

套件：

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

com.google.ads.afsn

自動蒐集的資料

AFS SDK 會自動收集以下資料。所有資料會從裝置傳出給 Google，以便放送廣告，且所有資料在傳輸過程中都會經過加密。我們絕不會收集使用者的個人資訊，除非應用程式在使用者查詢中傳送這類資料。

資料 蒐集資料的用途如下...
IP 位址 摘要：
  • 詐欺防範、安全性和法規遵循
  • 廣告或行銷
  • 取得大概位置
，瞭解如何調查及移除這項存取權。 詳細資料：
IP 位址的用途是監控詐欺和濫用行為，以及用來推測使用者的大概位置。

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

應用程式活動
  • 在應用程式中瀏覽及輕觸頁面的動作
  • 應用程式內搜尋記錄
 摘要：
  • 數據分析
  • 詐欺防範、安全性和法規遵循
  • 廣告或行銷
  • 個人化
，瞭解如何調查及移除這項存取權。 詳細資料：
應用程式向 Google 提供使用者查詢，以便我們傳回與關鍵字相關的搜尋廣告。我們會評估所傳回廣告的觀看次數和參與度 (輕觸)。
診斷資料 摘要：
  • 數據分析
，瞭解如何調查及移除這項存取權。 詳細資料：
SDK 會評估廣告的顯示延遲時間，以便導入及評估產品改善功能。此外，我們也會傳送當機報告/錯誤報告，偶爾會視需要加入其他檢測系統，以便瞭解發布商如何使用這些功能。
裝置或其他 ID 摘要：
  • 詐欺防範、安全性和法規遵循
  • 廣告或行銷
，瞭解如何調查及移除這項存取權。 詳細資料：
裝置 ID 可用於監控詐欺和濫用行為，以及評估廣告成效。