ترحيل SDK

تتناول هذه الصفحة عمليات نقل البيانات للإصدارات الحالية والسابقة.

النقل من الإصدار 23 إلى الإصدار 24

توضّح الأقسام الفرعية التالية التغييرات غير المتوافقة والاختلافات في السلوك بين الإصدارَين الرئيسيين 23 و24 من "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة".

الحد الأدنى لمستوى واجهة برمجة تطبيقات Android هو 23

اعتبارًا من الإصدار 24.0.0، تتطلّب حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة أن تعمل جميع التطبيقات على المستوى 23 من واجهة برمجة التطبيقات (API) لنظام التشغيل Android كحدّ أدنى. لضبط مستوى واجهة برمجة التطبيقات، غيِّر قيمة minSdk في ملف build.gradle على مستوى التطبيق إلى 23 أو أعلى.

تغييرات على التحميل والتهيئة المحسّنَين

يكون الخيار التلقائي للعلمَين OPTIMIZE_INITIALIZATION وOPTIMIZE_AD_LOADING هو true. لمزيد من المعلومات حول هذه العلامات، يُرجى الاطّلاع على تحسين عملية التهيئة والتحميل.

إزالة التبعيتَين firebase-ads وfirebase-ads-lite

بدءًا من الإصدار 24.0.0، لم تعُد إصدارات حزمة تطوير البرامج (SDK) توفّر التبعيتَين firebase-ads وfirebase-ads-lite. استخدِم التبعية play-services-ads بدلاً من ذلك.

إزالة واجهات برمجة التطبيقات المتوقّفة نهائيًا الخاصة بالاتجاهات من "الإعلانات على شاشة فتح التطبيق"

  • تمت إزالة طرق AppOpenAd.load() التي تقبل مَعلمة إدخال خاصة بالاتجاه. استخدِم طرق AppOpenAd.load() لا تتطلّب تحديد اتجاه بدلاً من ذلك.
  • تمت إزالة التعداد AppOpenAdOrientation.

تبسيط وظيفة ردّ الاتصال الخاصة بالمكافآت لمحوّلات التوسّط

يضيف الإصدار 24.0.0 الدالة onUserEarnedReward() في MediationRewardedAdCallback ويوقف نهائيًا الدالة onUserEarnedReward(RewardItem). يجب أن تبدأ برامج التكيّف مع التوسّط في طلب onUserEarnedReward() عندما يحصل المستخدم على مكافأة.

عند إعادة توجيه عمليات ردّ الاتصال من وسيطاء التوسّط، تعرض جميع إصدارات "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" المكافأة المحدّدة في واجهة مستخدم AdMob في OnUserEarnedRewardListener.

تمت إزالة الصفوف

تمت إزالة الصفوف التالية بدون استبدالها:

  • DynamicHeightSearchAdRequest
  • SearchAdRequest
  • SearchAdView

الطُرق التي تمت إزالتها

تمت إزالة الطرق التالية بدون استبدالها:

الفئة الطريقة
RewardedInterstitialAdLoadCallback onRewardedInterstitialAdLoaded()
onRewardedInterstitialAdFailedToLoad(int)
onRewardedInterstitialAdFailedToLoad(LoadAdError)

الطُرق المتوقّفة نهائيًا

تم إيقاف الطرق التالية بدون توفير بديل:

الفئة الطريقة
مُنسّق loadInterscrollerAd()
RtbAdapter loadRtbInterscrollerAd()

النقل من الإصدار 22 إلى الإصدار 23

توضّح الأقسام الفرعية التالية التغييرات غير المتوافقة والاختلافات في السلوك بين الإصدارَين الرئيسيين 22 و23 من "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة".

الحد الأدنى لمستوى واجهة برمجة تطبيقات Android هو 21

اعتبارًا من الإصدار 23.0.0، تتطلّب حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة أن يكون الحد الأدنى لمستوى واجهة برمجة التطبيقات (API) في جميع التطبيقات هو 21 لكي تعمل. لضبط مستوى واجهة برمجة التطبيقات، غيِّر قيمة minSdkVersion في ملف build.gradle على مستوى التطبيق إلى 21 أو أعلى.

إزالة الطرق القديمة أو استبدالها

الإصدار 22.0.0 من واجهة برمجة التطبيقات الإصدار 23.0.0 من واجهة برمجة التطبيقات
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

توضّح الأقسام الفرعية التالية التغييرات غير المتوافقة والاختلافات في السلوك بين الإصدارَين 21 و22 الرئيسيين من "SDK لإعلانات Google على الأجهزة الجوّالة".

استخدِم MobileAds.getVersion() للحصول على إصدار "SDK لإعلانات Google على الأجهزة الجوّالة"

تمت إزالة طريقة MobileAds.getVersionString() في الإصدار 22.0.0 واستبدالها بطريقة MobileAds.getVersion().

تعرض الطريقة الجديدة رقم الإصدار الخارجي المتوقّع، مثل 22.0.0. لمزيد من المعلومات حول هذا التغيير، يُرجى الاطّلاع على مقالة استخدام طريقة getVersion() الإصدار الجديد من حزمة "SDK لإعلانات Google على الأجهزة الجوّالة".

الطرق التي تمت إزالتها أو استبدالها

يسرد الجدول التالي التغييرات المحدّدة في الإصدار 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 Adapter
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

نقل البيانات من الإصدار 20 إلى الإصدار 21

توضّح الأقسام الفرعية التالية التغييرات غير المتوافقة والاختلافات في السلوك بين الإصدارَين الرئيسيين 20 و21 من "SDK لإعلانات Google على الأجهزة الجوّالة":

تعديل minSdkVersion إلى 19 أو إصدار أحدث

اعتبارًا من الإصدار 21.0.0، تتطلّب حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة أن تعمل جميع التطبيقات على المستوى 19 من واجهة برمجة التطبيقات Android API كحدّ أدنى. لضبط مستوى واجهة برمجة التطبيقات، غيِّر قيمة minSdkVersion في ملف الإصدار الخاص بتطبيقك إلى 19 أو أعلى.

فرض إمكانية القيم الخالية

استعدادًا لفرض إمكانية القيم الخالية بشكل صارم، تتم إضافة التعليقات التوضيحية @NonNull إلى جميع واجهات برمجة التطبيقات التي لم تحدّد إمكانية القيم الخالية بشكل صريح في السابق.

قد يؤدي هذا التغيير إلى حدوث أعطال في تطبيقات Kotlin والتطبيقات التي تستخدم أُطر عمل للتحقّق من القيم الفارغة في Java، وذلك في حال حدوث انتهاكات لأمان القيم الفارغة وعدم التعامل مع قيم null بطريقة آمنة في السابق (راجِع مستندات Kotlin حول أمان القيم الفارغة).

إزالة طريقة addNetworkExtras()

تم إيقاف الطريقة addNetworkExtras() التي تنقل مَعلمات إضافية كعنصر NetworkExtras إلى محوّل شبكة إعلانية معيّن نهائيًا في الإصدار 20.3.0 من حزمة SDK، وستتم إزالتها في الإصدار 21.0.0. استخدِم طريقة addNetworkExtrasBundle() من فئة AdRequest.Builder نفسها بدلاً من ذلك.

إزالة طرق تحديد الموقع الجغرافي

ستتم إزالة طرق تحديد الموقع الجغرافي التالية في الإصدار 21.0.0:

  • الطريقة setLocation(Location location) في الفئة AdRequest.Builder التي تحدّد الموقع الجغرافي للمستخدم لأغراض الاستهداف في التوسّط.
  • الطريقة getLocation() في الفئة AdRequest التي تعرض معلومات استهداف الموقع الجغرافي للمستخدم التي تم تمريرها سابقًا إلى الطريقة setLocation(Location location)
  • الطريقة getLocation() في الفئة MediationAdConfiguration التي تعرض الموقع الجغرافي للمستخدم، إذا تم تحديده بواسطة AdRequest.

لا تستخدم Google بيانات الموقع الجغرافي لاستهداف الإعلانات. عليك استخدام واجهات برمجة التطبيقات التابعة لجهات خارجية لتوفير المعلومات لشبكات الإعلانات التابعة لجهات خارجية إذا كان ذلك مطلوبًا.

إيقاف واجهات الأحداث المخصّصة نهائيًا

تتيح الأحداث المخصّصة للناشرين الذين يستخدمون ميزة "توسّط AdMob" إعداد مصدر إعلانات للعرض بدون انقطاع لا يمثّل أحد مصادر الإعلانات المتوافقة مع AdMob.

تم إيقاف جميع واجهات الأحداث المخصّصة نهائيًا، ويُنصح باستخدام الفئة Adapter والواجهة MediationAdLoadCallback بدلاً منها.

يسرد الجدول التالي الفئة أو الواجهة المناسبة التي يجب استخدامها لكل واجهة حدث مخصّص بدءًا من الإصدار 21.0.0:

واجهات الإصدار 20.0.0 فئة/ واجهة الإصدار 21.0.0
CustomEvent Adapter
CustomEventBanner
CustomEventInterstitial
CustomEventNative
CustomEventBannerListener Adapter, MediationAdLoadCallback
CustomEventInterstitialListener
CustomEventListener
CustomEventNativeListener

نقل البيانات من الإصدار 19 إلى الإصدار 20

تتضمّن الإصدار 20.0.0 العديد من التغييرات غير المتوافقة مع الإصدارات السابقة. قدّم الإصدار 19.7.0 العديد من واجهات برمجة التطبيقات الجديدة، كما أوقف أو أعاد تسمية العديد من الفئات استعدادًا للإصدار 20.0.0. يسلّط هذا الدليل الضوء على التغييرات الرئيسية في الإصدار 20.0.0.

تعديلات على واجهة برمجة التطبيقات الخاصة بتنسيق ملء الشاشة

بدءًا من الإصدار 20.0.0، تم توحيد أشكال الإعلانات البينية والإعلانات التي تضم مكافأة والإعلانات البينية التي تضم مكافأة والإعلانات على شاشة فتح التطبيق لتتّبع تصميمًا متسقًا لواجهة برمجة التطبيقات.

تلتزم جميع واجهات برمجة التطبيقات الخاصة بتنسيقات ملء الشاشة بالمبادئ التالية:

  • طريقة تحميل ثابتة
  • آلية مشابهة للتعامل مع عمليات معاودة الاتصال أو معالجة التحميل
  • الاعتماد على فئة FullScreenContentCallback في عمليات معاودة الاتصال الخاصة بالعرض التقديمي

إزالة واجهة برمجة التطبيقات القديمة RewardedVideoAd API

تم طرح واجهة برمجة التطبيقات الأحدث RewardedAd لأول مرة في آذار (مارس) 2019، وهي واجهة برمجة التطبيقات المفضّلة للإعلانات مقابل مكافآت منذ أكثر من 18 شهرًا. وقد تم إجراء تحسينات أكثر على هذه الواجهة مقارنةً بواجهة برمجة التطبيقات القديمة RewardedVideoAd، بما في ذلك إمكانية تحميل أكثر من إعلان واحد مقابل مكافأة في المرة الواحدة.

تمت إزالة واجهة برمجة التطبيقات القديمة RewardedVideoAd في الإصدار 20.0.0 من حزمة تطوير البرامج (SDK).

إيقاف بانر الإعلانات الذكية نهائيًا لصالح إعلانات البانر التكيُّفية

لم نعُد نسمح بعرض إعلانات البانر الذكي، بل نسمح بعرض إعلانات البانر التكيُّفي. توفّر "إعلانات البانر التكيُّفية" أداءً أفضل ومرونة أكبر في ضبط عرض الإعلان. إذا كنت تفضّل مواصلة استخدام إعلانات بانر بعرض الصفحة الكاملة، يمكنك إجراء ذلك باستخدام إعلانات البانر التكيُّفية، كما هو موضّح في مقتطف الرمز التالي:

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. يُعلمك استخدام واجهة برمجة تطبيقات على مستوى نظام التشغيل كلما غادر المستخدمون تطبيقك، بغض النظر عمّا إذا كان ذلك بسبب تفاعل مع إعلان أم لا.

يُرجى العِلم أنّ الغرض من وظيفة 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.OnCustomTemplateAdLoadedListener nativead.NativeCustomFormatAd.OnCustomFormatAdLoadedListener
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 مُزال
أداة الربط مُزال
search.SearchAdRequest مُزال
واجهة AdRequest.TagForUnderAgeOfConsent مُزال
Interface 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 لتتوافقا مع جميع أشكال الإعلانات بملء الشاشة.
  • تمت إزالة ميزات أداة الربط.
الفئة الإصدار 19.5.0 من واجهة برمجة التطبيقات الإصدار 20.0.0 من واجهة برمجة التطبيقات ملاحظات
AdSize getPortraitBannerAdSizeWithWidth() getPortraitAnchoredAdaptiveBannerAdSize()
getLandscapeBannerAdSizeWithWidth() getLandscapeAnchoredAdaptiveBannerAdSize()
getCurrentOrientationBannerAdSizeWithWidth() getCurrentOrientationAnchoredAdaptiveBannerAdSize()
MobileAds initialize(Context, String) MobileAds.initialize(Context, OnInitializationCompleteListener) تم الآن ضبط معرّف التطبيق في ملف AndroidManifest.xml.
initialize(Context, String, MobileAds.Settings) initialize(Context, OnInitializationCompleteListener) تم إيقاف فئة الإعدادات نهائيًا.
getRewardedVideoAdInstance() مُزال استخدِم واجهة برمجة التطبيقات RewardedAd بدلاً من ذلك.
AdListener onAdFailedToLoad(int) onAdFailedToLoad(LoadAdError)
onAdLeftApplication() مُزال تستخدم أشكال الإعلانات بملء الشاشة FullscreenContentCallback بدلاً من AdListener، ولا تتوفّر طريقة مكافئة في FullscreenContentCallback. تمت إزالة الطريقة من AdListener.
VideoController getAspectRatio() MediaContent.getAspectRatio()
AdRequest getGender() مُزال
getBirthday() مُزال
getNetworkExtras() مُزال
setManualImpressionsEnabled() مُزال
updateCorrelator() مُزال راجِع مقالة فلترة محتوى الإعلانات.
AdRequest.Builder setBirthday() مُزال
setGender() مُزال
setIsDesignedForFamilies() مُزال اطّلِع على الدليل.
addTestDevice() RequestConfiguration.Builder.setTestDeviceIds() اطّلِع على تفعيل الإعلانات التجريبية.
tagForChildDirectedTreatment() RequestConfiguration.Builder.setTagForChildDirectedTreatment() راجِع مقالة فلترة محتوى الإعلانات.
setTagForUnderAgeOfConsent() RequestConfiguration.Builder.setTagForUnderAgeOfConsent()
setMaxAdContentRating() RequestConfiguration.Builder.setMaxAdContentRating()
AdView getMediationAdapterClassName() ResponseInfo.getMediationAdapterClassName() يتوفّر العنصر ResponseInfo باستخدام الطريقة AdView، getResponseInfo().
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 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 الآن أسلوب التحميل الثابت نفسه الذي تستخدمه تنسيقات ملء الشاشة الأخرى.
setAdListener()
DynamicHeightSearchAdRequest getNetworkExtras() مُزال تم إيقاف الفئة NetworkExtras نهائيًا.
AdLoader forContentAd() مُزال
forAppInstallAd() مُزال
withCorrelator() مُزال
getMediationAdapterClassName() مُزال