Trang này được dịch bởi Cloud Translation API.

Di chuyển SDK

Trang này trình bày cách di chuyển đối với phiên bản hiện tại và phiên bản cũ.

Di chuyển từ phiên bản 23 sang phiên bản 24

Các tiểu mục sau đây mô tả các thay đổi có thể gây lỗi và sự khác biệt về hành vi giữa phiên bản lớn 23 và 24 của SDK quảng cáo trên thiết bị di động của Google.

Cấp độ API Android tối thiểu là 23

Kể từ phiên bản 24.0.0, SDK quảng cáo trên thiết bị di động của Google yêu cầu tất cả ứng dụng phải chạy trên API Android cấp 23 trở lên. Để điều chỉnh cấp độ API, hãy thay đổi giá trị minSdk trong tệp build.gradle ở cấp ứng dụng thành 23 trở lên.

Các thay đổi đối với hoạt động khởi chạy và tải được tối ưu hoá

Theo mặc định, các cờ OPTIMIZE_INITIALIZATION và OPTIMIZE_AD_LOADING được đặt thành true. Để biết thêm thông tin về các cờ này, hãy xem phần Tối ưu hoá quá trình khởi chạy và tải.

Xoá các phần phụ thuộc firebase-ads và firebase-ads-lite

Kể từ phiên bản 24.0.0, các bản phát hành SDK không còn phân phối các phần phụ thuộc firebase-ads và firebase-ads-lite. Thay vào đó, hãy sử dụng phần phụ thuộc play-services-ads.

Xoá các API hướng không dùng nữa cho quảng cáo khi mở ứng dụng

Xoá các phương thức AppOpenAd.load() chấp nhận tham số đầu vào hướng. Thay vào đó, hãy sử dụng các phương thức AppOpenAd.load() không có hướng.
Xoá enum AppOpenAdOrientation.

Đơn giản hoá lệnh gọi lại phần thưởng cho bộ chuyển đổi dàn xếp

Phiên bản 24.0.0 thêm lệnh gọi lại onUserEarnedReward() trong MediationRewardedAdCallback và ngừng sử dụng onUserEarnedReward(RewardItem). Bộ chuyển đổi dàn xếp phải bắt đầu gọi onUserEarnedReward() khi người dùng nhận được phần thưởng.

Khi chuyển tiếp lệnh gọi lại từ các bộ chuyển đổi dàn xếp, tất cả phiên bản SDK quảng cáo trên thiết bị di động của Google sẽ trả về phần thưởng được xác định trong giao diện người dùng AdMob trong OnUserEarnedRewardListener.

Các lớp đã bị xoá

Các lớp sau đã bị xoá mà không có lớp thay thế:

DynamicHeightSearchAdRequest
SearchAdRequest
SearchAdView

Các phương thức đã bị xoá

Các phương thức sau đã bị xoá mà không có phương thức thay thế:

Lớp	Phương thức
RewardedInterstitialAdLoadCallback	`onRewardedInterstitialAdLoaded()`
	`onRewardedInterstitialAdFailedToLoad(int)`
	`onRewardedInterstitialAdFailedToLoad(LoadAdError)`

Các phương thức không dùng nữa

Các phương thức sau đây không còn được dùng nữa và không có phương thức thay thế:

Lớp	Phương thức
Adapter (Người chuyển thể)	`loadInterscrollerAd()`
RtbAdapter	`loadRtbInterscrollerAd()`

Di chuyển từ phiên bản 22 sang phiên bản 23

Các tiểu mục sau đây mô tả các thay đổi có thể gây lỗi và sự khác biệt về hành vi giữa phiên bản lớn 22 và 23 của SDK quảng cáo trên thiết bị di động của Google.

Cấp độ API Android tối thiểu là 21

Kể từ phiên bản 23.0.0, SDK quảng cáo trên thiết bị di động của Google yêu cầu tất cả ứng dụng phải có API Android cấp 21 trở lên để có thể chạy. Để điều chỉnh cấp độ API, hãy thay đổi giá trị của minSdkVersion trong tệp build.gradle ở cấp ứng dụng thành 21 trở lên.

Xoá/thay thế các phương thức không dùng nữa

API phiên bản 22.0.0	API phiên bản 23.0.0
AdRequest.Builder.addTestDevice()	RequestConfiguration.Builder.setTestDeviceIds()
AdRequest.Builder.tagForChildDirectedTreatment()	RequestConfiguration.Builder.setTagForChildDirectedTreatment()
AdRequest.Builder.setIsDesignedForFamilies()	RequestConfiguration.Builder.setMaxAdContentRating()
AdFormat.UNKNOWN	Không có phương án thay thế
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()

Di chuyển từ phiên bản 21 sang phiên bản 22

Các tiểu mục sau đây mô tả các thay đổi có thể gây lỗi và sự khác biệt về hành vi giữa phiên bản chính 21 và 22 của SDK quảng cáo trên thiết bị di động của Google.

Sử dụng MobileAds.getVersion() để tải phiên bản SDK Quảng cáo của Google trên thiết bị di động

Phương thức MobileAds.getVersionString() bị xoá trong phiên bản 22.0.0 và thay bằng MobileAds.getVersion().

Phương thức mới sẽ trả về số phiên bản bên ngoài dự kiến. Ví dụ: 22.0.0. Để biết thêm thông tin về thay đổi này, hãy xem bài viết Sử dụng phương thức getVersion() mới của SDK Quảng cáo của Google trên thiết bị di động.

Phương thức bị xoá hoặc thay thế

Bảng sau đây liệt kê các thay đổi cụ thể trong phiên bản 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	Trình chuyển đổi
MediationRewardedVideoAdListener	Trình chuyển đổi
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

Di chuyển từ phiên bản 20 sang phiên bản 21

Các tiểu mục sau đây mô tả các thay đổi có thể gây lỗi và sự khác biệt về hành vi giữa phiên bản chính 20 và 21 của SDK quảng cáo trên thiết bị di động của Google:

Cập nhật minSdkVersion lên phiên bản 19 trở lên

Kể từ phiên bản 21.0.0, SDK quảng cáo trên thiết bị di động của Google yêu cầu tất cả ứng dụng phải có API Android cấp 19 trở lên để có thể chạy. Để điều chỉnh cấp độ API, hãy thay đổi giá trị của minSdkVersion trong tệp bản dựng của ứng dụng thành cấp 19 trở lên.

Thực thi tính chất rỗng nghiêm ngặt

Để chuẩn bị cho việc thực thi tính chất rỗng nghiêm ngặt, chú thích @NonNull sẽ được thêm vào tất cả những API chưa xác định rõ ràng tính chất rỗng.

Thay đổi này có thể khiến các ứng dụng Kotlin và những ứng dụng sử dụng khung kiểm tra giá trị rỗng của Java gặp lỗi nếu vi phạm quy định về sự an toàn cho giá trị rỗng và chưa xử lý các giá trị null theo cách an toàn (xem Tài liệu của Kotlin về sự an toàn cho giá trị rỗng).

Xoá phương thức addNetworkExtras()

Phương thức addNetworkExtras() truyền các thông số bổ sung dưới dạng bản sao NetworkExtras đến một bộ chuyển đổi mạng quảng cáo cụ thể đã ngừng hoạt động trong SDK phiên bản 20.3.0 và sẽ bị xoá trong phiên bản 21.0.0. Hãy sử dụng phương thức addNetworkExtrasBundle() từ cùng một lớp AdRequest.Builder.

Xoá các phương thức định vị

Các phương thức định vị sau sẽ bị xoá trong phiên bản 21.0.0:

Phương thức setLocation(Location location) trong lớp AdRequest.Builder sẽ đặt vị trí của người dùng để nhắm mục tiêu theo nhóm dàn xếp.
Phương thức getLocation() trong lớp AdRequest trả về thông tin nhắm mục tiêu theo vị trí của người dùng trước đó đã được chuyển đến phương thức setLocation(Location location).
Phương thức getLocation() trong lớp MediationAdConfiguration trả về vị trí của người dùng, nếu được AdRequest xác định.

Google không sử dụng dữ liệu vị trí để nhắm mục tiêu quảng cáo. Nếu bắt buộc, bạn nên sử dụng API của bên thứ ba để cung cấp thông tin cho các mạng quảng cáo bên thứ ba.

Ngừng sử dụng giao diện sự kiện tuỳ chỉnh

Sự kiện tuỳ chỉnh cho phép nhà xuất bản sử dụng tính năng Dàn xếp AdMob thiết lập nguồn quảng cáo dạng thác nước không phải là một trong các nguồn quảng cáo được hỗ trợ của AdMob.

Tất cả giao diện sự kiện tuỳ chỉnh sẽ ngừng hoạt động và thay vào đó là lớp Adapter và giao diện MediationAdLoadCallback.

Bảng sau đây liệt kê những lớp hoặc giao diện tương ứng mà bạn phải sử dụng cho từng giao diện sự kiện tuỳ chỉnh kể từ phiên bản 21.0.0:

Giao diện phiên bản 20.0.0	Lớp/ Giao diện phiên bản 21.0.0
CustomEvent	Trình chuyển đổi
CustomEventBanner
CustomEventInterstitial
CustomEventNative
CustomEventBannerListener	Adapter, MediationAdLoadCallback
CustomEventInterstitialListener
CustomEventListener
CustomEventNativeListener

Di chuyển từ phiên bản 19 sang phiên bản 20

Có nhiều thay đổi có thể gây lỗi trong phiên bản 20.0.0. Phiên bản 19.7.0 ra mắt nhiều API mới, loại bỏ và đổi tên nhiều lớp để chuẩn bị cho phiên bản 20.0.0. Hướng dẫn này nêu bật những thay đổi chính trong phiên bản 20.0.0.

Nội dung cập nhật đối với API theo định dạng toàn màn hình

Kể từ phiên bản 20.0.0, các định dạng quảng cáo xen kẽ, quảng cáo có tặng thưởng, quảng cáo xen kẽ có tặng thưởng và quảng cáo khi mở ứng dụng được chuẩn hoá để tuân theo một thiết kế API nhất quán.

Tất cả các API theo định dạng toàn màn hình đều tuân theo các nguyên tắc sau:

Phương thức tải tĩnh
Cơ chế tải lệnh gọi lại hoặc trình xử lý tương tự
Sử dụng lớp FullScreenContentCallback để gọi lại bản trình bày

Xoá API RewardedVideoAd cũ

API RewardedAd mới được ra mắt lần đầu vào tháng 3 năm 2019 và là API có tặng thưởng được ưa thích trong hơn 18 tháng qua. API này có nhiều tính năng nâng cao hơn so với API RewardedVideoAd cũ, kể cả khả năng tải nhiều quảng cáo có tặng thưởng cùng lúc.

API RewardedVideoAd cũ sẽ bị xoá trong SDK phiên bản 20.0.0.

Biểu ngữ thông minh sẽ ngừng hoạt động và được thay thế bằng biểu ngữ thích ứng

Quảng cáo biểu ngữ thông minh sẽ ngừng hoạt động và được thay thế bằng quảng cáo biểu ngữ thích ứng. Biểu ngữ thích ứng mang lại hiệu quả hoạt động vượt trội và tính linh hoạt cao hơn trong việc đặt chiều rộng quảng cáo. Nếu muốn tiếp tục sử dụng biểu ngữ có chiều rộng đầy đủ, bạn vẫn có thể làm vậy bằng cách sử dụng biểu ngữ thích ứng, theo cách minh hoạ trong đoạn mã sau đây:

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

Xoá lệnh gọi lại ứng dụng

Lệnh gọi lại onAdLeftApplication cho tất cả các định dạng quảng cáo đã bị xoá và được thay thế bằng ProcessLifecycleOwner. Khi sử dụng API ở cấp hệ điều hành, bạn sẽ nhận được thông báo mỗi khi người dùng rời khỏi ứng dụng, bất kể việc đó có phải là do một hành động tương tác với quảng cáo hay không.

Xin lưu ý rằng lệnh gọi lại onAdLeftApplication không có chức năng như một trình xử lý lượt nhấp quảng cáo, và việc dựa vào lệnh gọi lại này để báo cáo lượt nhấp sẽ không cung cấp chỉ số chính xác. Ví dụ: một lượt nhấp vào biểu tượng Lựa chọn quảng cáo làm khởi chạy một trình duyệt bên ngoài đã kích hoạt lệnh gọi lại, nhưng không được tính là một lượt nhấp.

Đổi tên lớp

Bảng sau đây liệt kê các lớp cụ thể đã thay đổi hoặc bị xoá:

Hầu hết các lớp có liên quan đến UnifiedNativeAd đều đã được đổi tên thành NativeAd.
Các lớp và chế độ xem MobileAds.Settings, NativeExpressAdView, NativeAppInstallAd, NativeContentAd và InstreamAd đều đã bị xoá.
Tất cả các lớp có tiền tố Publisher đều đã được thay thế bằng tiền tố AdManager.
Tên gói InterstitialAd đã thay đổi.

Lớp 19.5.0	Lớp 20.0.0
com.google.android.gms.ads.	com.google.android.gms.ads.
reward.RewardedVideoAd	rewarded.RewardedAd
reward.RewardedVideoAdListener	rewarded.RewardedAdLoadCallback và 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.OnCustomTemplateAdLoadedListener	nativead.NativeCustomFormatAd.OnCustomFormatAdLoadedListener
MobileAds.Settings	Đã xoá
doubleclick.PublisherAdRequest	admanager.AdManagerAdRequest
doubleclick.PublisherAdView	admanager.AdManagerAdView
formats.PublisherAdViewOptions	formats.AdManagerAdViewOptions
doubleclick.PublisherInterstitialAd	admanager.AdManagerInterstitialAd
InterstitialAd	interstitial.InterstitialAd
NativeExpressAdView	Đã xoá
instream.InstreamAd	Đã xoá
mediation.admob.AdMobExtras	Đã xoá
Correlator	Đã xoá
search.SearchAdRequest	Đã xoá
Giao diện AdRequest.TagForUnderAgeOfConsent	Đã xoá
Giao diện AdRequest.MaxAdContentRating	Đã xoá
formats.NativeAppInstallAd	native.NativeAd
formats.NativeAppInstallAdView	native.NativeAdView
mediation.NativeAppInstallAdMapper	mediation.UnifiedNativeAdMapper
formats.NativeContentAd	native.NativeAd
formats.NativeContentAdView	native.NativeAdView
mediation.NativeContentAdMapper	mediation.UnifiedNativeAdMapper

Xoá/thay thế một số phương thức

Bảng sau đây liệt kê các thay đổi cụ thể trong phiên bản 20.0.0:

Các phương thức khởi động lỗi thời đã bị xoá khỏi lớp MobileAds.
Một số phương thức từ lớp AdRequest.Builder() đã bị xoá hoặc chuyển sang lớp RequestConfiguration.
API RewardedAd và InterstitialAd đã được cập nhật để phù hợp với tất cả các định dạng toàn màn hình.
Các tính năng tương quan đều đã bị xoá.

Lớp	API phiên bản 19.5.0	API phiên bản 20.0.0	Ghi chú
AdSize	getPortraitBannerAdSizeWithWidth()	getPortraitAnchoredAdaptiveBannerAdSize()
	getLandscapeBannerAdSizeWithWidth()	getLandscapeAnchoredAdaptiveBannerAdSize()
	getCurrentOrientationBannerAdSizeWithWidth()	getCurrentOrientationAnchoredAdaptiveBannerAdSize()
MobileAds	initialize(Context, String)	MobileAds.initialize(Context, OnInitializationCompleteListener)	Mã ứng dụng hiện được đặt trong AndroidManifest.xml.
	initialize(Context, String, MobileAds.Settings)	initialize(Context, OnInitializationCompleteListener)	Lớp Cài đặt không còn được hỗ trợ nữa.
	getRewardedVideoAdInstance()	Đã xoá	Thay vào đó, hãy sử dụng RewardedAd API.
AdListener	onAdFailedToLoad(int)	onAdFailedToLoad(LoadAdError)
AdListener	onAdLeftApplication()	Đã xoá	Các định dạng quảng cáo toàn màn hình sử dụng FullscreenContentCallback thay cho AdListener và không có phương thức tương đương trên FullscreenContentCallback. Phương thức này đã bị xoá khỏi AdListener.
VideoController	getAspectRatio()	MediaContent.getAspectRatio()
AdRequest	getGender()	Đã xoá
	getBirthday()	Đã xoá
	getNetworkExtras()	Đã xoá
	setManualImpressionsEnabled()	Đã xoá
	updateCorrelator()	Đã xoá	Xem phần Cách lọc nội dung quảng cáo.
AdRequest.Builder	setBirthday()	Đã xoá
	setGender()	Đã xoá
	setIsDesignedForFamilies()	Đã xoá	Xem hướng dẫn.
	addTestDevice()	RequestConfiguration.Builder.setTestDeviceIds()	Xem bài viết Bật quảng cáo thử nghiệm.
	tagForChildDirectedTreatment()	RequestConfiguration.Builder.setTagForChildDirectedTreatment()	Xem phần Cách lọc nội dung quảng cáo.
	setTagForUnderAgeOfConsent()	RequestConfiguration.Builder.setTagForUnderAgeOfConsent()
	setMaxAdContentRating()	RequestConfiguration.Builder.setMaxAdContentRating()
AdView	getMediationAdapterClassName()	ResponseInfo.getMediationAdapterClassName()	Bạn có thể sử dụng đối tượng `ResponseInfo` bằng phương thức `AdView`, `getResponseInfo()`.
NativeAdOptions	setImageOrientation()	setMediaAspectRatio()
NativeAdOptions	getImageOrientation	getMediaAspectRatio()
RewardedAd	loadAd(AdRequest, RewardedAdLoadCallback)	RewardedAd.load(Context, String, AdRequest, RewardedAdLoadCallback)	RewardedAd hiện sử dụng phương pháp tải tĩnh giống như các định dạng toàn màn hình khác.
	loadAd(PublisherAdRequest, RewardedAdLoadCallback)	RewardedAd.load(Context, String, AdManagerAdRequest, RewardedAdLoadCallback)
	isLoaded()	Đã xoá	Lệnh gọi lại từ phương thức tải tĩnh sẽ cung cấp quảng cáo đã được tải.
	show(Activity, RewardedAdCallback)	show(Activity, OnUserEarnedRewardListener)	Phương thức hiển thị này tuân thủ phương pháp rộng hơn về định dạng toàn màn hình.
RewardedAdLoadCallback	onRewardedAdFailedToLoad(int)	onAdFailedToLoad(LoadAdError)
	onRewardedAdFailedToLoad(LoadAdError)	onAdFailedToLoad(LoadAdError)
	onRewardedAdLoaded()	onAdLoaded(RewardedAd)
AppOpenAdLoadCallback	onAppOpenAdFailedToLoad(int)	onAdFailedToLoad(LoadAdError)
	onAppOpenAdFailedToLoad(LoadAdError)	onAdFailedToLoad(LoadAdError)
	onAppOpenAdLoaded(AppOpenAd)	onAdLoaded(AppOpenAd)
RewardedInterstitialAdLoadCallback	onRewardedInterstitialAdFailedToLoad(int)	onAdFailedToLoad(LoadAdError)
	onRewardedInterstitialAdFailedToLoad(LoadAdError)	onAdFailedToLoad(LoadAdError)
	onRewardedInterstitialAdLoaded(RewardedInterstitialAd)	onAdLoaded(RewardedInterstitialAd)
InterstitialAd	new InterstitialAd()	InterstitialAd.load(Context, String, AdRequest, InterstitialAdLoadCallback)	InterstitialAd hiện sử dụng cùng một phương thức tải tĩnh giống như các định dạng toàn màn hình khác.
InterstitialAd	setAdListener()
DynamicHeightSearchAdRequest	getNetworkExtras()	Đã xoá	Lớp NetworkExtras không còn được dùng nữa.
AdLoader	forContentAd()	Đã xoá
	forAppInstallAd()	Đã xoá
	withCorrelator()	Đã xoá
	getMediationAdapterClassName()	Đã xoá