此页面由 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 实例，每个实例对应一个 case。
需要向构造函数提供您的网络媒体资源代码（发布商 ID），要应用于的样式 ID 返回的广告，以及 SearchAdOptions。构造函数中提供的 Context 必须是 Activity，其中包含 SearchAdController，并且您在将放置广告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

通过对ViewcreateAdView() 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 中定义。