SDK 遷移

本頁面提供目前和先前版本的遷移作業。

從 v22 遷移至 v23

最低 Android API 級別為 21

自 23.0.0 版起,所有應用程式都必須搭載 Android API 級別 21 以上版本,才能執行 Google Mobile Ads SDK。如要調整 API 級別,請將應用程式層級 build.gradle 檔案中的 minSdkVersion 值變更為 21 以上。

繼承自父類別的 AdManagerAdRequest.Builder 方法可鏈結

在 23.0.0 版中,沿用父項的 AdManagerAdRequest.Builder 方法可鏈結在一起,以單一呼叫建構 AdManagerAdRequest

Java

AdManagerAdRequest request = new AdManagerAdRequest.Builder()
    .addCustomTargeting("age", "25") // AdManagerAdRequest.Builder method.
    .setContentUrl("https://www.example.com") // Method inherited from parent.
    .build(); // Builds an AdManagerAdRequest.

Kotlin

var request = AdManagerAdRequest.Builder()
  .addCustomTargeting("age", "25") // AdManagerAdRequest.Builder method.
  .setContentUrl("https://www.example.com") // Method inherited from parent.
  .build() // Builds an AdManagerAdRequest.

已移除/取代的已淘汰方法

22.0.0 版 API 23.0.0 版 API
AdRequest.Builder.addTestDevice() RequestConfiguration.Builder.setTestDeviceIds()
AdRequest.Builder.tagForChildDirectedTreatment() RequestConfiguration.Builder.setTagForChildDirectedTreatment()
AdRequest.Builder.setIsDesignedForFamilies() RequestConfiguration.Builder.setMaxAdContentRating()
AdFormat.UNKNOWN 無替代項目
AdLoader.Builder.forUnifiedNativeAd() AdLoader.Builder.forNativeAd()
AdLoader.Builder.forCustomTemplateAd() AdLoader.Builder.forCustomFormatAd()
AdLoader.Builder.withNativeAdOptions(com.google.android.gms.ads.formats.NativeAdOptions) AdLoader.Builder.withNativeAdOptions(com.google.android.gms.ads.nativead.NativeAdOptions)
void MobileAds.setSameAppKeyEnabled() boolean MobileAds.putPublisherFirstPartyIdEnabled()

從 v21 遷移至 v22

使用 MobileAds.getVersion() 取得 Google Mobile Ads SDK 版本

已從 22.0.0 版中移除 MobileAds.getVersionString() 方法,改用 MobileAds.getVersion()

新方法會傳回預期的外部版本號碼,例如 22.0.0。如要進一步瞭解這項變更,請參閱「使用新版 Google Mobile Ads SDK getVersion() 方法」。

移除已淘汰的 NativeCustomFormatAd.getVideoMediaView()

第 21 版,Google Mobile Ads SDK 提供了 NativeCustomFormatAd.getVideoMediaView() 方法,讓您取得原生自訂廣告格式的媒體素材資源。

版本 22 開始,您要建立自己的 MediaView 並設定其媒體內容,並使用 MediaContent.getVideoController() 取得影片控制項。

v22

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
    // Assumes you have a FrameLayout in your view hierarchy with the id media_placeholder.
    FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

    MediaContent mediaContent = ad.getMediaContent();
    if (mediaContent != null && mediaContent.hasVideoContent()) {
        // Create a MediaView and set its media content.
        MediaView mediaView = new MediaView(mediaPlaceholder.getContext());
        mediaView.setMediaContent(mediaContent);
        mediaPlaceholder.addView(mediaView);
    }
}

v21

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
    // Assumes you have a FrameLayout in your view hierarchy with the id media_placeholder.
    FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

    VideoController videoController = ad.getVideoController();
    if (videoController.hasVideoContent()) {
        // Add the media view provided by the native ad.
        mediaPlaceholder.addView(ad.getVideoMediaView());
    }
}

詳情請參閱自訂原生廣告指南。

已移除或取代的方法

下表列出了 22.0.0 版的特定變更內容。

v21.0.0 v22.0.0
MobileAds.getVersionString() MobileAds.getVersion()
NativeCustomFormatAd.getVideoMediaView() NativeCustomFormatAd.getMediaContent()
NativeCustomFormatAd.getVideoController() NativeCustomFormatAd.getMediaContent().getVideoController()
AdRequest.Builder.setAdInfo() AdRequest.Builder.setAdString()
MediationRewardedVideoAdAdapter Adapter
MediationRewardedVideoAdListener
com.google.android.gms.ads.mediation.VersionInfo com.google.android.gms.ads.VersionInfo
com.google.android.gms.ads.doubleclick.AppEventListener com.google.android.gms.ads.admanager.AppEventListener

從 v20 遷移至 v21

將 minSdkVersion 更新至 19 以上

從 21.0.0 版起,所有應用程式都必須搭載 Android API 級別 19 以上版本,才能執行 Google Mobile Ads SDK。如要調整 API 級別,請將應用程式建構檔案中的 minSdkVersion 值變更為 19 以上。

強制執行嚴格的是否可為空值設定

為了強制執行嚴格的是否可為空值設定,先前未明確定義是否可為空值的所有 API 都會新增 @NonNull 註解。

如果含有空值安全性違規行為,且先前未以安全的方式處理 null 值,這項變更可能會破壞使用 Java 空值檢查架構的 Kotlin 應用程式和應用程式 (請參閱 Null-safety 相關 Kotlin 說明文件)。

移除 addNetworkExtras() 方法

在 SDK 20.3.0 版中,以 NetworkExtras 執行個體傳遞額外參數至特定廣告聯播網轉接程式的 addNetworkExtras() 方法已淘汰,並將在 21.0.0 版中移除。請改用相同 AdRequest.Builder 類別的 addNetworkExtrasBundle() 方法。

移除定位方式

下列位置方法將在 21.0.0 版中移除:

  • AdRequest.Builder 類別中的 setLocation(Location location) 方法,用於設定使用者的位置,以便進行中介服務指定。
  • AdRequest 類別中的 getLocation() 方法會傳回先前傳遞至 setLocation(Location location) 方法的使用者指定地區資訊。
  • MediationAdConfiguration 類別中的 getLocation() 方法會回傳使用者的位置 (如果由 AdRequest 定義)。

Google 不會使用位置資料來指定廣告。您應視情況使用第三方 API,向第三方廣告聯播網提供資訊。

淘汰自訂事件介面

使用自訂事件,發布商就能使用 Ad Manager中介服務,為不屬於「 Ad Manager」支援的廣告聯播網的廣告聯播網新增刊登序列中介服務。

所有自訂事件介面已淘汰,並改用 Adapter 類別和 MediationAdLoadCallback 介面。

下表列出自 21.0.0 版起,應用於每個自訂事件介面的對應類別或介面:

v20.0.0 介面 v21.0.0 類別/ 介面
CustomEvent Adapter
CustomEventBanner
CustomEventInterstitial
CustomEventNative
CustomEventBannerListener Adapter MediationAdLoadCallback
CustomEventInterstitialListener
CustomEventListener
CustomEventNativeListener

從 v19 遷移至第 20 版

版本 20.0.0 中有多項破壞性變更。19.7.0 版推出了許多新的 API,並為了準備版本 20.0.0 而淘汰或重新命名許多類別。本指南重點說明 20.0.0 版的主要異動內容。

全螢幕格式 API 更新

自 20.0.0 版起,插頁式、獎勵、插頁式獎勵廣告和應用程式開啟頁面廣告格式已標準化,以遵循一致的 API 設計。

所有全螢幕格式 API 皆採用下列原則:

移除舊版 RewardsVideoAd API

新版 RewardedAd API 於 2019 年 3 月首次推出,成為推薦獎勵 API 已超過 18 個月。與舊版 RewardedVideoAd API 相比,此 API 強化了更多功能,包括一次載入多則獎勵廣告。

舊版 RewardedVideoAd API 已從 SDK 20.0.0 版中移除。

系統將淘汰智慧型橫幅廣告,改用自動調整橫幅廣告

淘汰智慧型橫幅廣告,改用自動調整橫幅廣告。自動調整橫幅廣告能帶來卓越的成效,且更靈活地設定廣告寬度。假如您偏好繼續使用全寬度橫幅廣告,還是可以採用自動調整橫幅廣告,如以下程式碼片段所示:

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。無論使用者是否離開應用程式,使用 OS 層級 API 都會通知您。

請注意,onAdLeftApplication 回呼從未想為廣告點擊處理常式,使用此回呼來回報點擊次數並不會產生準確指標。舉例來說,當使用者點擊啟動外部瀏覽器的 AdChoices 圖示時,系統叫用回呼,但不計為一次點擊。

重新命名課程

下表列出變更或移除的特定類別名稱。簡單來說:

  • 大多數與 UnifiedNativeAd 相關的類別已重新命名為 NativeAd
  • 已移除 MobileAds.SettingsNativeExpressAdViewNativeAppInstallAdNativeContentAdInstreamAd 類別和檢視畫面。
  • 包含 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 獎勵.RewardsAdLoadCallback 和 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
format.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 已移除
AdRequest.TagForUnderAgeOfConsent 介面 已移除
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 類別。
  • 為配合所有全螢幕格式,獎勵廣告和 插頁式廣告 API 皆已更新。
  • 已移除 Correlator 功能。
類別 19.5.0 版 API 20.0.0 版 API 附註
AdSize getPortrait 橫幅AdSizeWithWidth() getPortraitAnchoredAdaptiveBannerAdSize()
getLandscapeBannerAdSizeWithWidth() getLandscapeAnchoredAdaptiveBannerAdSize()
getCurrentOrientationBannerAdSizeWithWidth() getCurrentOrientationAnchoredAdaptiveBannerAdSize()
MobileAds initialize(Context, String) MobileAds.initialize(Context, OnInitializationCompleteListener) AndroidManifest.xml 現已設定應用程式 ID。
initialize(Context, String, MobileAds.Settings) initialize(Context, OnInitializationCompleteListener) 「設定」類別已淘汰。
get 獎勵 VideoAdInstance() 已移除 請改用 RewardsAd API。
AdListener onAdFailedToLoad(int) onAdFailedToLoad(LoadAdError)
onAdLeftApplication() 已移除 全螢幕廣告格式使用 FullscreenContentCallback 取代 AdListener,且 FullscreenContentCallback 沒有對等的方法。此方法已從 AdListener 中移除。
VideoController getAspectRatio() MediaContent.getAspectRatio()
PublisherAdRequest getGender() 已移除
getBirthday() 已移除
getNetworkExtras() 已移除
setManualImpressionEnabled() 已移除
updateCorrelator() 已移除 請參閱「廣告素材篩選」一文。
PublisherAdRequest.Builder setBirthday() 已移除
setGender() 已移除
setIsDesignedForFamilies() 已移除 請參閱指南
addTestDevice() RequestConfiguration.Builder.setTestDeviceIds() 請參閱啟用測試廣告一文。
tagForChildDirectedTreatment() RequestConfiguration.Builder.setTagForChildDirectedTreatment() 請參閱「廣告素材篩選」一文。
setTagForUnderAgeOfConsent() RequestConfiguration.Builder.setTagForUnderAgeOfConsent()
setMaxAdContentRating() RequestConfiguration.Builder.setMaxAdContentRating()
AdView getMediationAdapterClassName() ResponseInfo.getMediationAdapterClassName() 您現在可透過 AdView 方法 getResponseInfo() 取得 ResponseInfo 物件。
NativeAdOptions setImageOrientation() setMediaAspectRatio()
getImageOrientation getMediaAspectRatio()
RewardedAd loadAd(AdRequest, RewardsAdLoadCallback) RIAd.load(Context, String, AdRequest, RewardsAdLoadCallback) 獎勵廣告現在採用的靜態載入方式與其他全螢幕格式相同。
loadAd(PublisherAdRequest, RewardsAdLoadCallback) RIAd.load(Context, String, AdManagerAdRequest, RewardsAdLoadCallback)
isLoaded() 已移除 靜態載入方法的回呼會提供已載入的廣告。
show(Activity, RewardedAdCallback) show(Activity, OnUserEarnedRewardListener) 此顯示方法遵循更廣泛的全螢幕格式做法。
RewardedAdLoadCallback onRIAdFailedToLoad(int) onAdFailedToLoad(LoadAdError)
on 獎勵 AdFailedToLoad(LoadAdError) onAdFailedToLoad(LoadAdError)
onRewardedAdLoaded() onAdLoaded(RewardedAd)
AppOpenAdLoadCallback onAppOpenAdFailedToLoad(int) onAdFailedToLoad(LoadAdError)
onAppOpenAdFailedToLoad(LoadAdError) onAdFailedToLoad(LoadAdError)
onAppOpenAdLoaded(AppOpenAd) onAdLoaded(AppOpenAd)
獎勵插頁式 AdLoad回呼 on 獎勵插頁式廣告FailedToLoad(int) onAdFailedToLoad(LoadAdError)
on 獎勵插頁式廣告FailedToLoad(LoadAdError) onAdFailedToLoad(LoadAdError)
on 獎勵插頁式 AdLoaded(Rewarded 插頁式廣告廣告) onAdLoaded(插頁式插頁式廣告)
PublisherInterstitialAd new PublisherInterstitialAd() 插頁式 Ad.load(Context, String, AdRequest, FLEDGEAdLoadCallback) 插頁式廣告現在採用的靜態載入方式與其他全螢幕格式相同。
setAdListener()
DynamicHeightSearchAd要求 getNetworkExtras() 已移除 NetworkExtras 類別已淘汰。
AdLoader forContentAd() 已移除
forAppInstallAd() 已移除
withCorrelator() 已移除
getMediationAdapterClassName() 已移除