本頁面涵蓋目前和先前版本的遷移作業。
從第 24 版遷移至第 25 版
以下各子節說明 Google Mobile Ads SDK (Legacy) 主要版本 24 和 25 之間的破壞性變更和行為差異。
Android API 最低級別為 24
自 25.5.0 版起,Google Mobile Ads SDK (Legacy) 要求所有應用程式在 Android API 級別 24 以上版本執行。如要調整 API 級別,請將應用程式層級 build.gradle 檔案中的 minSdk 值變更為 24 以上。
移除已淘汰的廣告回呼
從下列類別中移除下列已淘汰的廣告回呼:
| 類別 | 已移除回呼 | 替換 |
|---|---|---|
| SignalCallbacks |
onFailure(String)onAdFailedToShow(String)
|
onFailure(AdError)onAdFailedToShow(AdError)
|
| MediationAdLoadCallback | ||
| MediationInterstitialAdCallback | ||
| MediationRewardedAdCallback |
錨定自動調整橫幅廣告大小 API 異動
25.0.0 版淘汰現有的錨定自動調整橫幅廣告大小 API,並推出大型錨定自動調整橫幅廣告的大小 API。Google Mobile Ads SDK (Legacy)可使用新的大型錨定自動調整橫幅廣告大小 API,向橫幅廣告放送影片需求。
下表詳細列出已淘汰的大小調整 API 及其替代項目:
| v24 (已淘汰) | v25 (替換) |
|---|---|
getCurrentOrientationAnchoredAdaptiveBannerAdSize(Context, int) |
getLargeAnchoredAdaptiveBannerAdSize(Context, int) |
getLandscapeAnchoredAdaptiveBannerAdSize(Context, int) |
getLargeLandscapeAnchoredAdaptiveBannerAdSize(Context, int) |
getPortraitAnchoredAdaptiveBannerAdSize(Context context, int width) |
getLargePortraitAnchoredAdaptiveBannerAdSize(Context context, int width) |
移除 mediation.VersionInfo 類別
com.google.android.gms.ads.mediation 套件中的 VersionInfo 類別已移除。請改用 com.google.android.gms.ads.VersionInfo 套件。
移除 RtbSignalData 類別中的 getConfiguration() 方法
RtbSignalData 中已淘汰的 getConfiguration() API 方法已移除。請改用 getConfigurations() 方法,該方法會傳回 List<MediationConfiguration> 清單。
從 v23 遷移至 v24
以下各子節說明 Google Mobile Ads SDK (Legacy) 主要版本 23 和 24 之間的破壞性變更和行為差異。
Android API 級別最低需求為 23
自 24.0.0 版起,Google Mobile Ads SDK (Legacy) 要求所有應用程式至少在 Android API 級別 23 上執行。如要調整 API 級別,請將應用程式層級 build.gradle 檔案中的 minSdk 值變更為 23 以上。
最佳化初始化和載入程序的異動
根據預設,OPTIMIZE_INITIALIZATION 和 OPTIMIZE_AD_LOADING 旗標會設為 true。如要進一步瞭解這些標記,請參閱「最佳化初始化和載入作業」。
已移除 firebase-ads 和 firebase-ads-lite 依附元件
自 24.0.0 版起,SDK 版本不再發布 firebase-ads 和 firebase-ads-lite 依附元件。請改用 play-services-ads 依附元件。
設定自訂指定目標參數
如要為廣告請求設定自訂指定目標,請使用 addCustomTargeting()。
移除應用程式開啟頁面廣告中已淘汰的方向 API
- 已移除接受螢幕方向輸入參數的
AppOpenAd.load()方法。請改用不採用方向的AppOpenAd.load()方法。 - 已移除
AppOpenAdOrientation列舉。
簡化中介服務轉接程式的獎勵回呼
24.0.0 版在 MediationRewardedAdCallback 中新增 onUserEarnedReward() 回呼,並淘汰 onUserEarnedReward(RewardItem)。使用者獲得獎勵時,中介服務轉接程式必須開始呼叫 onUserEarnedReward()。
轉送中介服務轉接程式的回呼時,所有 Google Mobile Ads SDK (Legacy) 版本都會傳回 Ad Manager 使用者介面中 OnUserEarnedRewardListener 定義的獎勵。
已移除課程
下列類別已移除,且沒有任何替代項目:
DynamicHeightSearchAdRequestSearchAdRequestSearchAdView
已移除的方法
下列方法已移除,且沒有替代方法:
| 類別 | 方法 |
|---|---|
| RewardedInterstitialAdLoadCallback | onRewardedInterstitialAdLoaded() |
onRewardedInterstitialAdFailedToLoad(int) |
|
onRewardedInterstitialAdFailedToLoad(LoadAdError) |
已淘汰的方法
下列方法已淘汰,且沒有替代方法:
| 類別 | 方法 |
|---|---|
| 變壓器 | loadInterscrollerAd() |
| RtbAdapter | loadRtbInterscrollerAd() |
從第 22 版遷移至第 23 版
以下各子節說明 Google Mobile Ads SDK (Legacy) 主要版本 22 和 23 之間的破壞性變更和行為差異。
Android API 級別最低需求為 21
自 23.0.0 版起,Google Mobile Ads SDK (Legacy) 要求所有應用程式必須在 Android API 級別 21 以上版本執行。如要調整 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.
移除/取代已淘汰的方法
| v22.0.0 API | v23.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() |
從第 21 版遷移至第 22 版
以下各子節說明 Google Mobile Ads SDK (Legacy) 主要版本 21 和 22 之間的破壞性變更和行為差異。
使用 MobileAds.getVersion() 取得 Google Mobile Ads SDK (Legacy) 版本
MobileAds.getVersionString() 方法已在 22.0.0 版中移除,改用 MobileAds.getVersion()。
新方法會傳回預期的外部版本號碼,例如 22.0.0。如要進一步瞭解這項異動,請參閱「使用新的 Google Mobile Ads SDK getVersion() 方法」。
移除已淘汰的 NativeCustomFormatAd.getVideoMediaView()
在第 21 版中,Google Mobile Ads SDK (Legacy) 提供 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 | 轉接程式 |
| 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
下列子節說明 Google Mobile Ads SDK (Legacy) 主要版本 20 和 21 之間的破壞性變更和行為差異:
將 minSdkVersion 更新為 19 以上
自 21.0.0 版起,Google Mobile Ads SDK (Legacy) 要求所有應用程式必須在 Android API 級別 19 以上版本執行。如要調整 API 級別,請將應用程式建構檔案中的 minSdkVersion 值變更為 19 以上。
強制執行嚴格的是否可為空值
為強制執行嚴格的是否可為空值,我們在先前未明確定義是否可為空值的所有 API 中,新增了 @NonNull 註解。
如果發生空值安全違規,且先前未以安全方式處理 null 值,這項變更可能會破壞 Kotlin 應用程式和使用 Java 空值檢查架構的應用程式 (請參閱有關空值安全的 Kotlin 說明文件)。
移除 addNetworkExtras() 方法
addNetworkExtras() 方法會將額外參數做為 NetworkExtras 例項傳遞至特定廣告聯播網轉接程式,但該方法已在 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 將資訊提供給第三方廣告聯播網。
自訂事件介面淘汰
發布商可透過自訂事件,為非 Ad Manager 支援的廣告來源設定刊登序列廣告來源。
所有自訂事件介面都已淘汰,改用 Adapter 類別和 MediationAdLoadCallback 介面。
下表列出 21.0.0 以上版本中,每個自訂事件介面必須使用的對應類別或介面:
從第 19 版遷移至第 20 版
20.0.0 版有許多破壞性變更。19.7.0 版推出了許多新的 API,並淘汰或重新命名許多類別,為 20.0.0 版做好準備。本指南重點說明 20.0.0 版的主要異動。
全螢幕格式 API 更新
自 20.0.0 版起,插頁式、獎勵、插頁式獎勵廣告和應用程式開啟頁面廣告格式已標準化,採用一致的 API 設計。
所有全螢幕格式 API 都遵循下列原則:
- 靜態載入方法
- 類似的載入回呼或處理常式機制
- 依賴
FullScreenContentCallback類別處理顯示事件回呼
移除舊版 RewardedVideoAd API
較新的 RewardedAd API 於 2019 年 3 月首次推出,18 個多月以來一直是首選的獎勵 API。與舊版 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.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 |
nativead.NativeCustomFormatAd |
| 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類別。- RewardedAd 和 InterstitialAd API 已更新,與所有全螢幕格式一致。
- Correlator 功能已移除。
| 類別 | v19.5.0 API | v20.0.0 API | 附註 |
|---|---|---|---|
| AdSize | getPortraitBanner |
getPortraitAnchored |
|
| getLandscapeBanner |
getLandscapeAnchored |
||
| getCurrentOrientation |
|||
| MobileAds | initialize(Context, String) | MobileAds.initialize(Context, OnInitializationComplete |
應用程式 ID 現已在 AndroidManifest.xml 中設定完成。 |
| initialize(Context, String, MobileAds.Settings) | initialize(Context, OnInitializationComplete |
Settings 類別已淘汰。 | |
| getRewardedVideo |
已移除 | 請改用 RewardedAd API。 | |
| AdListener | onAdFailedToLoad(int) | onAd |
|
| onAdLeftApplication() | 已移除 | 全螢幕廣告格式會使用 FullscreenContentCallback 取代 AdListener,且 FullscreenContentCallback 沒有對應的方法。方法已從 AdListener 中移除。 | |
| VideoController | getAspectRatio() | MediaContent.getAspectRatio() | |
| PublisherAdRequest | getGender() | 已移除 | |
| getBirthday() | 已移除 | ||
| getNetworkExtras() | 已移除 | ||
| setManualImpressions |
已移除 | ||
| updateCorrelator() | 已移除 | 請參閱「廣告內容篩選」。 | |
| PublisherAdRequest.Builder | setBirthday() | 已移除 | |
| setGender() | 已移除 | ||
| setIsDesignedForFamilies() | 已移除 | 請參閱指南。 | |
| addTestDevice() | RequestConfiguration |
請參閱「啟用測試廣告」。 | |
| tagForChildDirectedTreatment() | RequestConfiguration |
請參閱「廣告內容篩選」。 | |
| setTagFor |
RequestConfiguration |
||
| setMaxAdContentRating() | RequestConfiguration |
||
| AdView | getMediationAdapter |
ResponseInfo |
您可以使用 AdView 方法 getResponseInfo() 取得 ResponseInfo 物件。 |
| NativeAdOptions | setImageOrientation() | setMediaAspectRatio() | |
| getImageOrientation | getMediaAspectRatio() | ||
| RewardedAd | loadAd(AdRequest, RewardedAdLoadCallback) | RewardedAd.load(Context, String, AdRequest, RewardedAdLoadCallback) | RewardedAd 現在與其他全螢幕格式一樣,採用靜態載入方式。 |
| loadAd(PublisherAdRequest, RewardedAdLoadCallback) | RewardedAd.load(Context, String, AdManagerAdRequest, RewardedAdLoadCallback) | ||
| isLoaded() | 已移除 | 靜態載入方法的回呼會提供已載入的廣告。 | |
| show(Activity, RewardedAdCallback) | show(Activity, OnUserEarnedRewardListener) | 這個顯示方法遵循更廣泛的全螢幕格式做法。 | |
| RewardedAdLoadCallback | onRewardedAd |
onAd |
|
| onRewardedAd |
onAd |
||
| onRewardedAdLoaded() | onAdLoaded(RewardedAd) | ||
| AppOpenAdLoadCallback | onAppOpenAd |
onAd |
|
| onAppOpenAd |
onAd |
||
| onAppOpenAd |
onAdLoaded(AppOpenAd) | ||
| RewardedInterstitialAdLoad |
onRewardedInterstitialAd |
onAd |
|
| onRewardedInterstitialAd |
onAd |
||
| onRewardedInterstitialAd |
onAd |
||
| PublisherInterstitialAd | new PublisherInterstitialAd() | InterstitialAd.load(Context, String, AdRequest, InterstitialAdLoadCallback) | InterstitialAd 現在與其他全螢幕格式一樣,採用相同的靜態載入方法。 |
| setAdListener() | |||
| DynamicHeightSearchAd |
getNetworkExtras() | 已移除 | NetworkExtras 類別已淘汰。 |
| AdLoader | forContentAd() | 已移除 | |
| forAppInstallAd() | 已移除 | ||
| withCorrelator() | 已移除 | ||
| getMediationAdapter |
已移除 |