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()
代码库或 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
实例,分别与每种情况各对应一个。 - 您需要向构造函数提供您的网络媒体资源代码(发布商 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
发起新的调用会清除所有缓存的广告和关联的广告键。)
- 将此对象传递给
SearchAdController
构造函数即可自定义广告的请求和展示方式。对SearchAdOptions.Builder
调用build()
以创建SearchAdOptions
对象。
View
- 对
SearchAdController
调用createAdView()
,创建一个用于保存广告的View
对象。一次最多可以展示一个广告,但随着时间的推移,可以重复使用同一个View
来展示不同的广告。
- 使用
SearchAdRequest
对SearchAdController
调用loadAds
方法,以发起异步广告请求。对SearchAdRequest.Builder
调用build()
以创建SearchAdRequest
对象。
- 实现此接口并将其传递给
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 中定义。