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

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

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；舉例來說，如果您有畫面讓廣告顯示在搜尋結果清單旁，另一個畫面則在特定產品詳細資料旁顯示廣告，那麼您應該建立兩個不同的 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 會清除所有快取廣告和相關聯的廣告鍵)。

SearchAdOptions

將這個物件傳遞至 SearchAdController 建構函式，即可自訂要求和顯示廣告的方式。在 SearchAdOptions.Builder 上呼叫 build()，建立 SearchAdOptions 物件。

View

針對 SearchAdController 呼叫 createAdView()，建立 View 物件以保留廣告。一次最多顯示一則廣告，但同一個 View 可以回收，以便於一段時間後顯示不同的廣告。

SearchAdRequest

使用 SearchAdRequest 呼叫 SearchAdController 上的 loadAds 方法，啟動非同步廣告請求。在 SearchAdRequest.Builder 上呼叫 build()，建立 SearchAdRequest 物件。

AdListener

實作這個介面並傳遞至 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 中定義。