本頁面由 Cloud Translation API 翻譯而成。

Android 專用 AdSense 搜尋廣告原生導入

Google Mobile Ads SDK 也支援自訂搜尋樣式。如果您的應用程式目前已經採用 Google Mobile Ads SDK，建議您改用 AFSMA SDK 版本。

如果您要從 18.1.0 以下版本升級至 19.0.0 以上版本，請參閱遷移指南。

必要條件

本導入指南假設您熟悉下列項目：

AdSense 自訂搜尋廣告使用自訂搜尋樣式
Android 應用程式開發

匯入 AFS Native SDK

新增 SDK

如要在應用程式中加入 AdSense 搜尋廣告原生 SDK，請按照下列步驟操作：

開啟應用程式模組目錄中的 build.gradle 檔案。針對最新版 SDK 在 dependencies 下新增建構規則：

dependencies {
  implementation 'com.google.android.gms:play-services-afs-native:19.1.0'
}

請確認頂層 build.gradle 包含對 google() 存放區或 maven { url "https://maven.google.com" } 的參照。

請按照這些步驟操作，在專案中加入 Google Play 獨立版本比對器外掛程式。套用這個外掛程式，當 AFS 原生 SDK 處於使用不相容的 Google Play 服務版本，而不再允許但可能會導致執行階段異常終止或者，您也可以將 failOnVersionConflict() ResolutionStrategy 套用至專案，以便在專案中使用不相容的 Google Play 服務版本時，導致建構錯誤。儲存變更，然後點選下方的「Sync Project with Gradle Files」。按一下工具列

使用 AndroidX 而非 Android 支援資料庫

從 17.0.0 版 SDK 開始，應用程式必須使用 Jetpack (AndroidX) 而非 Android 支援資料庫。相容性需求：

將 com.android.tools.build:gradle 設為 v3.2.1 以上版本。
將 compileSdkVersion 設為 28 以上。
更新應用程式以使用 Jetpack (AndroidX)；請遵循遷移至 AndroidX

類別

如要在應用程式中放送 AFS 原生廣告，請實作下列類別：

SearchAdController

這個類別負責非同步要求廣告、快取及擷取廣告，以及顯示廣告。
每個廣告情境都需要獨立的 SearchAdController；舉例來說一個畫面，在搜尋結果清單和其他項目旁顯示廣告顯示廣告與特定產品的詳細資料一同顯示時，您應該建立兩個不同的 SearchAdController 例項，每個情況各一個。
您必須提供網站資源代碼 (發布商編號)、要套用的樣式 ID 以及 SearchAdOptions。建構函式中提供的 Context 必須是包含 SearchAdController 的 Activity，也是您要放置廣告 View 的位置。
呼叫 loadAds 可表示新使用者搜尋，並發出非同步廣告要求。當您發出新的呼叫時，系統會從內部廣告快取中清除先前對 loadAds 呼叫時載入的廣告。
使用 createAdView 建立 View，以便顯示廣告素材。
廣告載入後，請使用先前透過 createAdView 產生的 View 呼叫 populateAdView，將已快取的廣告算繪至該 View。除了要填入的 View 之外，請提供 adKey，也就是用來專屬識別廣告的任意字串。這會將來自使用 adKey 的快取，因此當相同的 adKey 傳遞至未來的呼叫時至 populateAdView，系統都會傳回相同的廣告。舉例來說，如果第一次呼叫 populateAdView 時使用 adKey="keyA"，並顯示登山靴的廣告，那麼之後每次透過 adKey="keyA" 呼叫 populateAdView 時，都會填入相同的登山靴廣告。(發起新通話： loadAds 會清除所有快取廣告和相關廣告鍵)。

SearchAdOptions

將此物件傳遞至 SearchAdController 建構函式來自訂廣告方式以便系統要求並顯示在 SearchAdOptions.Builder 上呼叫 build()：建立 SearchAdOptions 物件。

View

在 SearchAdController 上呼叫 createAdView()，藉此建立 View 物件，以便保留廣告。一次最多會顯示一個廣告，但相同的View可以以便日後放送不同的廣告

SearchAdRequest

使用 SearchAdRequest 在 SearchAdController 上呼叫 loadAds 方法，以便啟動非同步廣告請求。透過以下裝置呼叫 build()： SearchAdRequest.Builder，用來建立 SearchAdRequest 物件。

AdListener

實作這個介面並傳遞至 SearchAdController 建構函式註冊多個狀態的回呼。
注意：系統不會針對已取消的要求 (對 loadAds 的呼叫，在第一次呼叫解析前已遭其他對 loadAds 的呼叫搶先) 呼叫 AdListener 回呼。

實作範例

以下範例說明如何在範例 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 需要使用 AdListener 物件，並搭配 onAdLoaded() 方法，才能通知應用程式廣告已準備好顯示。我們也建議您實作 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);
    }
};

AdListener 中定義了 onAdFailedToLoad() 回呼方法使用的常數。