SDK 遷移

本頁說明目前與先前版本的遷移作業。

從 v22 遷移至 v23

最低 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

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

MobileAds.getVersionString() 方法已在 22.0.0 版中移除，並改用 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 版的具體異動。

從 v20 遷移至 v21

將 minSdkVersion 更新至 19 以上版本

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

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

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

如果發生空值安全性違規，且先前並未以安全的方式處理 null 值，這項變更可能會破壞使用 Java 空值檢查架構的 Kotlin 應用程式和應用程式 (請參閱 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 向第三方廣告聯播網提供資訊。

淘汰自訂事件介面

自訂事件可讓發布商使用中介服務 設定刊登序列廣告來源，但該來源不是 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 類別處理呈現回呼

移除舊版 獎勵 VideoAd API

新版 RewardedAd API 是在 2019 年 3 月首次推出，一直是 18 個月以上的首選獎勵 API。與舊版 RewardedVideoAd API 相比，體驗更多功能，包括一次載入多個獎勵廣告。

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

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

智慧型橫幅廣告廣告已淘汰，並改用自動調整橫幅廣告。自動調整橫幅廣告能提供優異的效能，彈性地設定廣告寬度。如果您偏好繼續使用全寬橫幅廣告，仍然可以使用自動調整橫幅廣告來進行，如以下程式碼片段所示：

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

退出應用程式回呼移除作業

所有廣告格式的 onAdLeftApplication 回呼都已移除，並改用 ProcessLifecycleOwner。使用 OS 層級 API 時，無論使用者是否因為與廣告互動而離開應用程式，系統都會通知您。

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

重新命名類別

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

• 大多數與 UnifiedNativeAd 相關的類別已重新命名為 NativeAd。
• 已移除 MobileAds.Settings、NativeExpressAdView、NativeAppInstallAd、NativeContentAd 和 InstreamAd 類別和檢視畫面。
• 所有包含 Publisher 前置字串的類別都已替換為 AdManager 前置字串。
• InterstitialAd 套件名稱已變更。

移除/取代的方法

下表列出了 20.0.0 版的具體異動。摘要說明：

• 從 MobileAds 類別中移除過時的初始化方法。
• AdRequest.Builder() 類別中的部分方法已移除或移至 RequestConfiguration 類別。
• 更新 獎勵 Ad 和 插頁式廣告 API，以符合所有全螢幕格式。
• 已移除 Correlator 功能。