本頁面由 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

如要在應用程式中加入 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 服務版本使用 (而非允許建構應用程式，但可能會造成執行階段異常終止)，會導致 Gradle 建構錯誤。或者，將 failOnVersionConflict() ResolutionStrategy 套用至專案，在專案中使用不相容的 Google Play 服務版本時產生建構錯誤。儲存變更，然後按一下工具列中的「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」一文中的指示操作。

類別

若要在應用程式中放送 AdSense 搜尋廣告原生廣告，請導入下列類別：

SearchAdController

這個類別負責以非同步方式請求廣告、快取、擷取廣告，以及顯示廣告。
每個廣告情境都需要單獨的 SearchAdController；例如，如果您的畫面顯示搜尋結果清單，另一個畫面顯示特定產品的詳細資料，那麼您應該建立兩個不同的 SearchAdController 例項，每個畫面各一個。
必須提供建構函式代碼 (發布商 ID)、樣式 ID 以套用至傳回廣告，以及 SearchAdOptions。建構函式中提供的 Context 必須是包含 SearchAdController 的 Activity，且您要放置廣告 View。
呼叫 loadAds 即可指出新的使用者搜尋並啟動非同步廣告請求。系統會在發出新呼叫時，從先前對 loadAds 呼叫載入的所有廣告，從內部廣告快取中清除。
使用 createAdView 建立 View，以顯示廣告素材。
廣告載入後，請使用先前使用 createAdView 產生的 View 呼叫 populateAdView，以便在該 View 中顯示快取廣告。除了要填入的 View 外，也請提供 adKey (這是用來識別廣告的任意字串)。這會將快取傳回的特定廣告素材與該 adKey 建立關聯，因此當相同的 adKey 傳遞至日後對 populateAdView 的呼叫時，系統便會傳回相同的廣告。舉例來說，如果第一次使用 adKey="keyA" 呼叫 populateAdView 並轉譯登山靴廣告，則每次使用 adKey="keyA" 呼叫 populateAdView 時，都會填入同一個廣告供登山靴使用。(向 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 需要使用 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);
    }
};

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