Google 移动广告 SDK 还支持自定义搜索广告样式。如果您的应用已在使用 Google 移动广告 SDK,我们建议您改用 AFSMA SDK 版本。
如果您要从 18.1.0 或更低版本升级到 19.0.0 或更高版本,请参阅我们的迁移指南。
前提条件
本实现指南假定您熟悉以下内容:
- 采用自定义搜索广告样式的 AdSense 自定义搜索广告
- Android 应用开发
导入 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
实例,每种实例分别对应一个。 - 您需要向构造函数提供您的网络媒体资源代码(发布商 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 中定义。