SDK 迁移

本文介绍了现行版本和以往版本的迁移。

迁移至 SDK v21

为避免 Google 移动广告 SDK 21.0.0 版（计划于 2022 年初发布）的潜在构建失败，请遵循本指南中介绍的检查和指南。

将 minSdkVersion 更新为 19 或更高版本

从版本 21.0.0 开始，Google 移动广告 SDK 要求所有应用程序的最低 Android API 级别为 19 才能运行。要调整 API 级别，请将应用程序构建文件中的minSdkVersion的值更改为 19 或更高。

强制执行严格的可空性

为了准备强制执行严格的可空性， @NonNull注释被添加到以前没有明确定义可空性的所有 API 中。

如果存在 null 安全违规并且之前未以安全方式处理null值，则此更改可能会破坏 Kotlin 应用程序和使用 Java null 检查框架的应用程序（请参阅有关 Null-safety 的 Kotlin 文档）。

删除 addNetworkExtras() 方法

将额外参数作为NetworkExtras实例传递给特定广告网络适配器的addNetworkExtras()方法在 SDK 版本 20.3.0 中已弃用，并将在版本 21.0.0 中删除。请改用同一AdRequest.Builder类中的addNetworkExtrasBundle()方法。

删除定位方法

以下定位方法将在 21.0.0 版本中移除：

AdRequest.Builder类中的setLocation(Location location)方法，用于设置用户的位置以进行中介定位。
AdRequest类中的getLocation()方法返回之前传递给setLocation(Location location)方法的用户定位信息。
MediationAdConfiguration类中的getLocation()方法返回用户的位置（如果由AdRequest定义）。

Google 不会使用位置数据来定位广告。如果需要，您应该使用第三方 API 将信息提供给第三方广告网络。

自定义事件接口弃用

自定义事件使使用 AdMob中介的发布商可以为不属于AdMob支持的广告网络之一的广告网络添加瀑布中介。

所有自定义事件接口都已弃用，取而代之的是Adapter类和MediationAdLoadCallback接口。

下表列出了从 21.0.0 版本开始每个自定义事件接口应该使用的相应类或接口：

v20.0.0 接口	v21.0.0 类/接口
自定义事件	适配器
自定义事件横幅
自定义事件插页式
CustomEventNative
自定义事件横幅监听器	适配器,中介AdLoadCallback
CustomEventInterstitialListener
自定义事件监听器
CustomEventNativeListener

迁移至 SDK v20

我们即将在版本 20.0.0 中进行多项重要更改。为做好准备迎接版本 20.0.0，版本 19.7.0 中引入了许多新的 API，并弃用或重命名了许多类。本指南重点介绍了对版本 19.7.0 做出的重大更改，以及即将在版本 20.0.0（2021 年初）中推出的新功能。

关于全屏广告格式 API 的更新

从版本 20.0.0 开始，对插页式广告、激励广告、插页式激励广告和开屏广告格式进行了标准化处理，以采用一致的 API 设计。

所有全屏广告格式 API 均遵循以下设计原则：

静态加载方法
类似的加载回调函数或处理程序机制
展示回调函数需要依靠 FullScreenContentCallback 类

移除旧版 RewardedVideoAd API

较新版本的 RewardedAd API 于 2019 年 3 月首次推出，在之后超过 18 个月的时间里一直是首选激励广告 API。与旧版 RewardedVideoAd API 相比，新版 API 添加了多项改进，其中包括一次加载多个激励广告的功能。

SDK 版本 20.0.0 中移除了旧版 RewardedVideoAd API。

弃用智能横幅广告，改用自适应横幅广告

弃用了智能横幅广告，现在使用的是自适应横幅广告。自适应横幅广告的效果更好，可以让您更灵活地设置广告宽度。如果您希望继续使用全宽横幅广告，仍然可以通过自适应横幅广告实现，如以下代码段所示：

Java

public class MyActivity extends AppCompatActivity {
  ...
  private AdSize getFullWidthAdaptiveSize() {
    Display display = getWindowManager().getDefaultDisplay();
    DisplayMetrics outMetrics = new DisplayMetrics();
    display.getMetrics(outMetrics);

    float widthPixels = outMetrics.widthPixels;
    float density = outMetrics.density;

    int adWidth = (int) (widthPixels / density);
    return AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, adWidth);
  }
}

Kotlin

class MyActivity : AppCompatActivity() {
  ...
  private val adaptiveAdSize: AdSize
    get() {
      val display = windowManager.defaultDisplay
      val outMetrics = DisplayMetrics()
      display.getMetrics(outMetrics)

      val density = outMetrics.density

      var adWidthPixels = ad_view_container.width.toFloat()
      if (adWidthPixels == 0f) {
        adWidthPixels = outMetrics.widthPixels.toFloat()
      }

      val adWidth = (adWidthPixels / density).toInt()
      return AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, adWidth)
    }
}

移除退出应用回调函数

移除了所有广告格式的 onAdLeftApplication 回调函数，改为使用 ProcessLifecycleOwner。如果使用操作系统级 API，无论用户是否因广告互动而打开您的应用，只要他们退出应用，您都会收到通知。

请注意，千万不要将 onAdLeftApplication 回调函数用作广告点击处理程序，如果依赖此类回调函数来报告点击，将无法生成准确的指标。例如，用户点击“广告选择”图标时会启动外部浏览器，这时系统会调用该回调函数，但不会将其计为一次点击。

重命名类

下表列出了已更改或移除的具体类名称。总结如下：

与 UnifiedNativeAd 相关的大部分类均已重命名为 NativeAd。
已移除 MobileAds.Settings、NativeExpressAdView、NativeAppInstallAd、NativeContentAd 和 InstreamAd 类及视图。
对于所有带 Publisher 前缀的类，其前缀均已替换为 AdManager。
更改了 InterstitialAd 软件包名称。

19.5.0 中的类	20.0.0 中的类
com.google.android.gms.ads.	com.google.android.gms.ads.
reward.RewardedVideoAd	rewarded.RewardedAd
reward.RewardedVideoAdListener	rewarded.RewardedAdLoadCallback 和 FullScreenContentCallback
reward.RewardItem	rewarded.RewardItem
rewarded.RewardedAdCallback	OnUserEarnedRewardListener
formats.UnifiedNativeAdView	nativead.NativeAdView
formats.UnifiedNativeAd	nativead.NativeAd
formats.UnifiedNativeAdAssetNames	nativead.NativeAdAssetNames
formats.UnifiedNativeAd.OnUnifiedNativeAdLoadedListener	nativead.NativeAd.OnNativeAdLoadedListener
formats.AdChoicesView	nativead.AdChoicesView
formats.NativeAd.AdChoicesInfo	nativead.NativeAd.AdChoicesInfo
formats.MediaView	nativead.MediaView
formats.NativeAdViewHolder	nativead.NativeAdViewHolder
formats.NativeAdOptions	nativead.NativeAdOptions
formats.NativeCustomTemplateAd	nativead.NativeCustomFormatAd
formats.NativeCustomTemplateAd.OnCustomTemplateAdLoadedListener	nativead.NativeCustomFormatAd.OnCustomFormatAdLoadedListener
MobileAds.Settings	已移除
doubleclick.PublisherAdRequest	admanager.AdManagerAdRequest
doubleclick.PublisherAdView	admanager.AdManagerAdView
formats.PublisherAdViewOptions	formats.AdManagerAdViewOptions
doubleclick.PublisherInterstitialAd	admanager.AdManagerInterstitialAd
InterstitialAd	interstitial.InterstitialAd
NativeExpressAdView	已移除
instream.InstreamAd	已移除
mediation.admob.AdMobExtras	已移除
Correlator	已移除
search.SearchAdRequest	已移除
Interface AdRequest.TagForUnderAgeOfConsent	已移除
Interface AdRequest.MaxAdContentRating	已移除
formats.NativeAppInstallAd	native.NativeAd
formats.NativeAppInstallAdView	native.NativeAdView
mediation.NativeAppInstallAdMapper	mediation.UnifiedNativeAdMapper
formats.NativeContentAd	native.NativeAd
formats.NativeContentAdView	native.NativeAdView
mediation.NativeContentAdMapper	mediation.UnifiedNativeAdMapper

移除/替换的方法

下表列出了版本 20.0.0 中的具体更改。总结如下：

从 MobileAds 类中移除了过时的初始化方法。
移除了 AdRequest.Builder() 类中的部分方法，或将这些方法移到了 RequestConfiguration 类中。
更新了 RewardedAd 和 InterstitialAd API，以与所有全屏广告格式保持一致。
移除了 Correlator 功能。

类	v19.5.0 中的 API	v20.0.0 中的 API	备注
AdSize	getPortraitBannerAdSizeWithWidth()	getPortraitAnchoredAdaptiveBannerAdSize()
	getLandscapeBannerAdSizeWithWidth()	getLandscapeAnchoredAdaptiveBannerAdSize()
	getCurrentOrientationBannerAdSizeWithWidth()	getCurrentOrientationAnchoredAdaptiveBannerAdSize()
MobileAds	initialize(Context, String)	MobileAds.initialize(Context, OnInitializationCompleteListener)	现在，在 AndroidManifest.xml 中设置应用 ID。
	initialize(Context, String, MobileAds.Settings)	initialize(Context, OnInitializationCompleteListener)	Settings 类已弃用。
	getRewardedVideoAdInstance()	已移除	改用 RewardedAd API。
AdListener	onAdFailedToLoad(int)	onAdFailedToLoad(LoadAdError)
AdListener	onAdLeftApplication()	已移除	全屏广告格式使用 FullscreenContentCallback 代替 AdListener，而且 FullscreenContentCallback 中没有对应的方法。该方法已从 AdListener 移除。
VideoController	getAspectRatio()	MediaContent.getAspectRatio()
AdRequest	getGender()	已移除
	getBirthday()	已移除
	getNetworkExtras()	已移除
	setManualImpressionsEnabled()	已移除
	updateCorrelator()	已移除	请参阅广告内容过滤。
AdRequest.Builder	setBirthday()	已移除
	setGender()	已移除
	setIsDesignedForFamilies()	已移除	请参阅指南。
	addTestDevice()	RequestConfiguration.Builder.setTestDeviceIds()	请参阅启用测试广告。
	tagForChildDirectedTreatment()	RequestConfiguration.Builder.setTagForChildDirectedTreatment()	请参阅广告内容过滤。
	setTagForUnderAgeOfConsent()	RequestConfiguration.Builder.setTagForUnderAgeOfConsent()
	setMaxAdContentRating()	RequestConfiguration.Builder.setMaxAdContentRating()
AdView	getMediationAdapterClassName()	ResponseInfo.getMediationAdapterClassName()	现在，ResponseInfo 对象通过 AdView 方法 getResponseInfo() 提供。
NativeAdOptions	setImageOrientation()	setMediaAspectRatio()
NativeAdOptions	getImageOrientation	getMediaAspectRatio()
RewardedAd	loadAd(AdRequest, RewardedAdLoadCallback)	RewardedAd.load(Context, String, AdRequest, RewardedAdLoadCallback)	现在，RewardedAd 与其他全屏广告格式使用相同的静态加载方法。
	loadAd(PublisherAdRequest, RewardedAdLoadCallback)	RewardedAd.load(Context, String, AdManagerAdRequest, RewardedAdLoadCallback)	现在，RewardedAd 与其他全屏广告格式使用相同的静态加载方法。
	isLoaded()	已移除	静态加载方法的回调函数会提供已加载完成的广告。
	show(Activity, RewardedAdCallback)	show(Activity, OnUserEarnedRewardListener)	此 show 方法遵循更广泛的全屏广告格式方法。
RewardedAdLoadCallback	onRewardedAdFailedToLoad(int)	onAdFailedToLoad(LoadAdError)
	onRewardedAdFailedToLoad(LoadAdError)	onAdFailedToLoad(LoadAdError)
	onRewardedAdLoaded()	onAdLoaded(RewardedAd)
AppOpenAdLoadCallback	onAppOpenAdFailedToLoad(int)	onAdFailedToLoad(LoadAdError)
	onAppOpenAdFailedToLoad(LoadAdError)	onAdFailedToLoad(LoadAdError)
	onAppOpenAdLoaded(AppOpenAd)	onAdLoaded(AppOpenAd)
RewardedInterstitialAdLoadCallback	onRewardedInterstitialAdFailedToLoad(int)	onAdFailedToLoad(LoadAdError)
	onRewardedInterstitialAdFailedToLoad(LoadAdError)	onAdFailedToLoad(LoadAdError)
	onRewardedInterstitialAdLoaded(RewardedInterstitialAd)	onAdLoaded(RewardedInterstitialAd)
InterstitialAd	新 InterstitialAd()	InterstitialAd.load(Context, String, AdRequest, InterstitialAdLoadCallback)	现在，InterstitialAd 与其他全屏广告格式使用相同的静态加载方法。
InterstitialAd	setAdListener()		现在，InterstitialAd 与其他全屏广告格式使用相同的静态加载方法。
DynamicHeightSearchAdRequest	getNetworkExtras()	已移除	NetworkExtras 类已弃用。
AdLoader	forContentAd()	已移除
	forAppInstallAd()	已移除
	withCorrelator()	已移除
	getMediationAdapterClassName()	已移除