必要條件
本實作指南假設您已熟悉下列項目:
- AFS 自訂搜尋廣告 (CSA) 導入通訊協定
- Android 應用程式開發
- 將 Android 版 (現已成為 Google Play 服務) 的 Google Mobile Ads SDK 與 Android Studio 專案建立關聯。必須安裝 9.0.0 版的 Google Play 服務。
類別
如要在應用程式中放送 AFSMA 廣告 (也稱為動態高度搜尋廣告),請實作下列類別:
- 這個類別繼承自 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 可用於監控詐欺、濫用行為監控及廣告成效評估。 |