Google Mobile Ads SDK 也支援自訂搜尋樣式。如果您的應用程式已採用 Google Mobile Ads SDK,建議您改用 AFSMA SDK 版本。
如果您是從 18.1.0 以下版本升級至 19.0.0 以上版本,請參閱遷移指南。
必要條件
本實作指南假設您熟悉下列項目:
- 包含自訂搜尋樣式的 AdSense 自訂搜尋廣告
- Android 應用程式開發
匯入 AdSense 搜尋廣告原生 SDK
新增 SDK
若要在應用程式中加入 AFS 原生 SDK,請按照下列步驟操作:
開啟應用程式模組目錄中的 build.gradle
檔案。在 dependencies
底下為最新版 SDK 新增建構規則:
dependencies {
implementation 'com.google.android.gms:play-services-afs-native:19.0.3'
}
請確認頂層 build.gradle
包含 google()
存放區或 maven { url "https://maven.google.com" }
的參照。
請按照這些操作說明,在專案中加入 Google Play 獨立版本比對工具外掛程式。套用這個外掛程式會導致當 AFS 原生 SDK 與 Google Play 服務不相容的版本使用時,會發生 Gradle 建構錯誤,而不是允許應用程式建構,但這可能導致執行階段異常終止。或者,如果在專案中使用不相容的 Google Play 服務版本,對專案套用 failOnVersionConflict()
ResolutionStrategy,就會發生建構錯誤。儲存變更,然後按一下工具列中的「Sync Project with Gradle Files」。
使用 AndroidX 取代 Android 支援資料庫
從 SDK 版本 17.0.0
開始,應用程式必須使用 Jetpack (AndroidX) 程式庫,而非 Android 支援資料庫。相容性需求:
- 將
com.android.tools.build:gradle
設為 3.2.1 以上版本。 - 請將
compileSdkVersion
設為 28 以上。 - 更新應用程式以使用 Jetpack (AndroidX);請按照「遷移至 AndroidX」中的指示操作。
類別
如要在應用程式中放送 AFS 原生廣告,請實作下列類別:
- 這個類別負責以非同步方式要求廣告、快取及擷取廣告,以及顯示廣告。
- 每個廣告情境都需要個別的
SearchAdController
;舉例來說,如果您有畫面讓廣告顯示在搜尋結果清單旁,另一個畫面則在特定產品詳細資料旁顯示廣告,那麼您應該建立兩個不同的SearchAdController
例項,每個例項各一個。 - 建構函式必須提供您的網站資源代碼 (發布商 ID)、樣式 ID 以套用至傳回的廣告和
SearchAdOptions
。建構函式中提供的Context
必須是包含SearchAdController
和廣告View
的Activity
。 - 呼叫
loadAds
表示新的使用者搜尋並啟動非同步廣告請求。呼叫loadAds
時,從內部廣告快取載入的所有廣告都會從內部廣告快取中清除。 - 使用
createAdView
建立View
來顯示廣告素材。 - 廣告載入後,請使用先前使用
createAdView
產生的View
呼叫populateAdView
,以在View
中顯示快取廣告。除了要填入的View
之外,請提供adKey
,可明確識別廣告的任意字串。這會將快取傳回的特定廣告素材與該adKey
建立關聯,因此當相同的adKey
傳遞到日後對populateAdView
的呼叫時,系統會傳回相同的廣告。舉例來說,如果第一次使用adKey="keyA"
呼叫populateAdView
並顯示登山靴廣告,之後每次呼叫populateAdView
且使用adKey="keyA"
時,系統就會為健行靴子填入相同的廣告。(呼叫loadAds
會清除所有快取廣告和相關聯的廣告鍵)。
- 將這個物件傳遞至
SearchAdController
建構函式,即可自訂要求和顯示廣告的方式。在SearchAdOptions.Builder
上呼叫build()
,建立SearchAdOptions
物件。
View
- 針對
SearchAdController
呼叫createAdView()
,建立View
物件以保留廣告。一次最多顯示一則廣告,但同一個View
可以回收,以便於一段時間後顯示不同的廣告。
- 使用
SearchAdRequest
呼叫SearchAdController
上的loadAds
方法,啟動非同步廣告請求。在SearchAdRequest.Builder
上呼叫build()
,建立SearchAdRequest
物件。
- 實作這個介面並傳遞至
SearchAdController
建構函式,即可註冊多個狀態的回呼。 - 注意:如果要求已取消,系統就不會呼叫
AdListener
回呼 (對在第一個呼叫解析前再次呼叫loadAds
而先佔的loadAds
)。
導入範例
以下範例說明如何在 Activity
範例中建立 SearchAdController
。
// MainActivity.java implementation
// (MainActivity is a subclass of Activity)
SearchAdController adController;
// adContainer where we will place our ads in this example.
ViewGroup adContainer;
protected void onCreate(Bundle bundle){
super.onCreate(bundle);
adContainer = (ViewGroup) findViewById(...);
// Specify ad options (not required).
SearchAdOptions.Builder adOptionsBuilder = new SearchAdOptions.Builder();
adOptionsBuilder.setAdType(SearchAdOptions.AD_TYPE_TEXT);
adOptionsBuilder.setPrefetch(true);
adOptionsBuilder.setNumAdsRequested(3);
// Provide a callback to trigger when ads are loaded.
AdListener adListener = new AdListener() {
public void onAdLoaded() {
createAndShowAd();
}
};
// Instantiate the SearchAdController.
adController = new SearchAdController(this, "your-client-id", "your-style-id",
adOptionsBuilder.build(), adListener);
}
當使用者啟動查詢時,建立 SearchAdRequest
並在 SearchAdController
上呼叫 loadAds
,即可啟動非同步廣告請求。
// Create the request.
SearchAdRequest.Builder requestBuilder = new SearchAdRequest.Builder();
requestBuilder.setQuery("user query here");
// Load the ads.
adController.loadAds(requestBuilder.build());
導入 onAdLoaded
回呼,將已載入的廣告填入廣告檢視畫面。
private void createAndShowAd() {
// Create a new view that will contain the ad.
View adView = adController.createAdView();
// Attach the new view to the view hierarchy.
adContainer.addView(adView);
// Display the ad inside the adView. We need to provide an adKey to
// indicate which ad is to be displayed in the adView. In this example,
// since we only have one ad, we can provide any constant string. However,
// if you intend to display multiple ads, each ad you wish to display
// should be given a unique adKey of your choosing.
adController.populateAdView(adView, "demoAd");
}
與指定查詢相關的廣告現在會顯示在 adView
中。
調查錯誤
SearchAdController
需要帶有 onAdLoaded()
方法的 AdListener
物件,藉此通知應用程式廣告已準備好顯示。您也應實作 onAdFailedToLoad()
方法,以便偵測並修正錯誤。舉例來說,您可以使用下列 AdListener
對實作進行偵錯:
AdListener adListener = new AdListener() {
public void onAdLoaded() {
// Called when an ad is loaded.
Toast.makeText(MainActivity.this, "Ad Loaded",
Toast.LENGTH_SHORT).show();
Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");
}
public void onAdLeftApplication() {
// Called when an ad leaves the application
// (to go to the browser for example).
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.
Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode,
Toast.LENGTH_SHORT).show();
Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " +
errorCode);
}
};
onAdFailedToLoad()
回呼方法中使用的常數是在 AdListener 中定義。