适用于 Android 的 AFS 原生实现

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

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

前提条件

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

导入 AFS 原生 SDK

添加 SDK

要将 AFS 原生 SDK 添加到您的应用中,请执行以下操作:

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

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

确保顶层 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 设置为 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

  • 使用 SearchAdRequestSearchAdController 调用 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 中定义。