此页面由 Cloud Translation API 翻译。

适用于 Android 的 AFS 原生实现

Google 移动广告 SDK 还支持自定义搜索样式。如果您的应用已在使用 Google 移动广告 SDK，我们建议您使用 AFSMA SDK 版本。

如果您要从 18.1.0 或更早版本升级到 19.0.0 或更高版本，请参阅迁移指南。

前提条件

本实现指南假定您熟悉以下内容：

采用自定义搜索广告样式的 AdSense 自定义搜索广告
Android 应用开发

导入 AFS 原生 SDK

添加 SDK

如需将 AFS 原生 SDK 添加到您的应用中，请执行以下操作：

打开应用模块目录中的 build.gradle 文件。针对最新版 SDK，在 dependencies 下添加新的 build 规则：

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

确保顶级 build.gradle 包含对 google() 的引用 repo 或 maven { url "https://maven.google.com" }。

请按照这些说明操作，在您的项目中添加 Google Play Standalone Version Matcher 插件。当 AFS 原生 SDK 处于与不兼容的 Google Play 服务版本一起使用，而不是允许要构建的应用，但可能会导致运行时崩溃。或者，将 failOnVersionConflict() ResolutionStrategy 应用于您的项目，以便在项目中使用不兼容的 Google Play 服务版本时导致构建错误。保存更改，然后点击 Sync Project with Gradle Files 。

使用 AndroidX 而非 Android 支持库

从该 SDK 版本 17.0.0 开始，您的应用必须使用 Jetpack (AndroidX) 库代替 Android 支持库。兼容性要求：

将 com.android.tools.build:gradle 设置为 v3.2.1 或更高版本。
将 compileSdkVersion 设置为 28 或更高版本。
更新您的应用以使用 Jetpack (AndroidX)；请按照迁移到 AndroidX 中的说明操作。

类

要在您的应用中投放 AFS 原生广告，请实现以下类：

SearchAdController

此类负责异步请求广告、缓存和检索广告以及呈现广告。
每个广告情境都需要单独的 SearchAdController；例如，如果您有一个屏幕会在搜索结果列表旁边展示广告，而另一个屏幕会在特定商品的详细信息旁边展示广告，则应分别为这两种情况创建两个单独的 SearchAdController 实例。
您需要向构造函数提供您的网络媒体资源代码（发布商 ID），要应用于的样式 ID 返回的广告，以及 SearchAdOptions。构造函数中提供的 Context 必须是 Activity，其中包含 SearchAdController，并且您在将放置广告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 方法来发起异步广告请求通过以下号码致电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 需要使用 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 中定义。