适用于 Android 的 AFS 原生实现

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

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

前提条件

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

导入 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() 代码库或 maven { url "https://maven.google.com" } 的引用。

请按照这些说明在您的项目中添加 Google Play Standalone Version Matcher 插件。当 AFS 原生 SDK 与不兼容的 Google Play 服务版本搭配使用时，应用此插件会导致 Gradle build 错误，而不会允许应用进行构建，但可能会导致运行时崩溃。或者，对您的项目应用 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 必须是包含 SearchAdController 以及用于放置广告 View 的 Activity。
  • 调用 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 构造函数，即可注册多种状态的回调。
  • 注意：取消的请求（在第一次调用解析之前，对 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 中定义。