SDK 遷移

本頁面說明如何遷移目前和先前的版本。

從 v23 遷移至 v24

以下小節說明 Google Mobile Ads SDK 主要版本 23 和 24 之間的重大變更和行為差異。

最低 Android API 級別為 23

從 24.0.0 版開始，Google Mobile Ads SDK 要求所有應用程式都必須在 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 依附元件。

移除應用程式開啟頁面廣告已淘汰的螢幕方向 API

• 已移除接受方向輸入參數的 AppOpenAd.load() 方法。請改用不採用方向的 AppOpenAd.load() 方法。
• 已移除 AppOpenAdOrientation 列舉。

簡化中介服務介面的獎勵回呼

24.0.0 版在 MediationRewardedAdCallback 中新增 onUserEarnedReward() 回呼，並淘汰 onUserEarnedReward(RewardItem)。使用者獲得獎勵時，中介服務介面卡必須開始呼叫 onUserEarnedReward()。

轉送中介服務介面卡的後續回呼時，所有 Google Mobile Ads SDK 版本都會在 OnUserEarnedRewardListener 中傳回 AdMob 使用者介面中定義的獎勵。

已移除課程

下列類別已移除，且沒有任何更換內容：

• DynamicHeightSearchAdRequest
• SearchAdRequest
• SearchAdView

已移除方法

下列方法已移除，且沒有替代方法：

已淘汰的方法

下列方法已淘汰，且沒有替代方法：

從 v22 遷移至 v23

以下小節說明 Google Mobile Ads SDK 主要版本 22 和 23 之間的重大變更和行為差異。

最低 Android API 級別為 21

從 23.0.0 版開始，Google Mobile Ads SDK 規定所有應用程式都必須使用 Android API 級別 21 以上版本才能執行。如要調整 API 級別，請在應用程式層級的 build.gradle 檔案中，將 minSdkVersion 的值變更為 21 以上。

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

從 v21 遷移至 v22

以下小節說明 Google Mobile Ads SDK 主要版本 21 和 22 之間的重大變更和行為差異。

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

22.0.0 版已移除 MobileAds.getVersionString() 方法，並改用 MobileAds.getVersion()。

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

已移除或更換的方法

下表列出 22.0.0 版的具體變更：

從第 20 版遷移至第 21 版

以下小節說明 Google Mobile Ads SDK 主要版本 20 和 21 之間的重大變更和行為差異：

將 minSdkVersion 更新至 19 以上版本

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

強制執行嚴格空值性

為準備強制執行嚴格的空值性，先前未明確定義空值性的所有 API 都會新增 @NonNull 註解。

如果發生空值安全違規情形，且先前未以安全方式處理 null 值 (請參閱 Kotlin 文件中的空值安全)，這項變更可能會導致 Kotlin 應用程式和使用 Java 空值檢查架構的應用程式發生錯誤。

移除 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 將資訊提供給第三方廣告聯播網。

自訂事件介面已淘汰

發布商使用 AdMob 中介服務時，可透過自訂事件設定刊登序列廣告來源，但該來源必須是 AdMob 支援的廣告來源。

所有自訂事件介面都已淘汰，請改用 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 月推出，且已成為偏好的獎勵 API 超過 18 個月。與舊版 RewardedVideoAd API 相比，新版 API 經過更多強化，包括一次載入多個獎勵廣告的功能。

SDK 20.0.0 版已移除舊版 RewardedVideoAd API。

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

智慧型橫幅廣告已淘汰，建議改用自動調整橫幅廣告。自動調整橫幅廣告的成效更出色，且設定廣告寬度時更具彈性。如果您偏好繼續使用全寬橫幅，仍可使用自動調整橫幅，如下列程式碼片段所示：

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);
  }
}

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)
    }
}

離開應用程式回呼移除作業

為支援 ProcessLifecycleOwner，我們已移除所有廣告格式的 onAdLeftApplication 回呼。使用 OS 層級的 API 時，無論使用者離開應用程式的原因是否與廣告互動有關，您都會收到通知。

請注意，onAdLeftApplication 回呼從來就不是廣告點擊處理常式，因此依賴這個回呼回報點擊次數，無法產生準確的指標。舉例來說，點選 AdChoices 圖示啟動外部瀏覽器時，系統會叫用回呼，但不會計為點擊。

重新命名類別

下表列出已變更或移除的特定類別名稱：

• 與 UnifiedNativeAd 相關的大部分類別已重新命名為 NativeAd。
• 已移除 MobileAds.Settings、NativeExpressAdView、NativeAppInstallAd、NativeContentAd 和 InstreamAd 類別和檢視區塊。
• 所有以 Publisher 前置字串開頭的類別，都已替換為 AdManager 前置字串。
• InterstitialAd 套件名稱已變更。

已移除/取代的方法

下表列出 20.0.0 版的具體變更：

• MobileAds 類別已移除過時的初始化方法。
• AdRequest.Builder() 類別中的部分方法已移除或移至 RequestConfiguration 類別。
• 我們已更新 RewardedAd 和 InterstitialAd API，以配合所有全螢幕格式。
• 已移除關聯器功能。