本頁面由 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 服務版本，而不再允許但可能會導致執行階段異常終止或者，您也可以套用 failOnVersionConflict() ResolutionStrategy ，當 Google Play 版本不相容時，就會發生建構錯誤專案中會使用服務。儲存變更，然後點選下方的「Sync Project with Gradle Files」。按一下工具列

使用 AndroidX 而非 Android 支援資料庫

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

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

類別

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

SearchAdController

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

SearchAdOptions

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

View

建立 View 物件來存放廣告，方法是呼叫 createAdView() SearchAdController。一次最多會顯示一個廣告，但相同的View可以以便日後放送不同的廣告

SearchAdRequest

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

AdListener

實作這個介面並傳遞至 SearchAdController 建構函式註冊多個狀態的回呼。
注意：系統不會針對已取消的要求 (呼叫) 呼叫 AdListener 回呼對 loadAds 的呼叫，此物件在第一個呼叫之前，已被另一個對 loadAds 的呼叫先佔呼叫已解決)。

實作範例

以下範例說明如何在範例中建立 SearchAdController Activity。

//  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 並呼叫 loadAds SearchAdController 上，以便啟動非同步廣告請求。

// 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 中定義。