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 依附元件。

設定自訂指定目標參數

如要在廣告請求中設定自訂指定目標，請使用 addCustomTargeting()。

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

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

簡化中介服務轉接程式的獎勵回呼

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

轉送中介服務轉接程式的回呼時，所有 Google Mobile Ads SDK 版本都會在 OnUserEarnedRewardListener 中傳回 Ad Manager 使用者介面定義的獎勵。

已移除課程

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

• 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 以上。

可鏈結從父類別沿用的 AdManagerAdRequest.Builder 方法

在 23.0.0 版中，從父項繼承的 AdManagerAdRequest.Builder 方法可以鏈結在一起，透過單一呼叫建構 AdManagerAdRequest：

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

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

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

從 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() 方法」。

移除已淘汰的 NativeCustomFormatAd.getVideoMediaView()

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

從第 22 版開始，您可以建立自己的 MediaView 並設定其媒體內容，然後使用 MediaContent.getVideoController() 取得影片控制項。

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

// 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 版的具體變更：

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

自訂事件介面已淘汰

發布商可透過自訂事件，為非 Ad Manager 支援的廣告來源設定刊登序列廣告來源。

所有自訂事件介面都已淘汰，請改用 Adapter 類別和 MediationAdLoadCallback 介面。

下表列出從 21.0.0 版開始，每個自訂事件介面必須使用的對應類別或介面：

從 v19 遷移至 v20

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，以配合所有全螢幕格式。
• 已移除關聯器功能。