نقل حزمة تطوير البرامج (SDK)

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

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

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

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

تمت إزالة/استبدال الطرق المتوقفة

واجهة برمجة التطبيقات v22.0.0 واجهة برمجة التطبيقات v23.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)
إبطال MobileAds.setSameAppKeyEnabled() boolean MobileAds.putPublisherFirstPartyIdEnabled()

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

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

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

تعرض الطريقة الجديدة رقم الإصدار الخارجي المتوقع، مثل 22.0.0. لمزيدٍ من المعلومات عن هذا التغيير، اطّلِع على استخدام طريقة getVersion() الجديدة لإعلانات 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 محوّل
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

يجب تحديث minSdkVersion إلى 19 أو إصدار أحدث.

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

فرض قابلية صارمة للقيم الفارغة

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

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

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

في الإصدار 20.3.0 من حزمة تطوير البرامج (SDK)، تم إيقاف طريقة addNetworkExtras() التي تمرِّر المَعلمات الإضافية كمثيل NetworkExtras لمحوِّل شبكة إعلانات محدّد، وستتم إزالتها في الإصدار 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 محوّل
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 لم تكن تهدف أبدًا إلى أن تكون معالجًا للنقرات على الإعلانات، وأنّ الاعتماد على معاودة الاتصال هذا للإبلاغ عن النقرات لم يؤدِ إلى إنشاء مقياس دقيق. على سبيل المثال، أدّت النقرة على رمز "خيارات الإعلان" التي أدّت إلى تشغيل متصفّح خارجي إلى استدعاء معاودة الاتصال ولكن لم يتم احتسابها كنقرة.

عمليات إعادة تسمية الصف

يسرد الجدول أدناه أسماء فئات معيّنة تم تغييرها أو إزالتها. باختصار:

  • تمت إعادة تسمية معظم الصفوف ذات الصلة بـ "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 Rewards.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
format.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.TagForOverAgeOfConsent تمت إزالتها
واجهة 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.
  • تم تحديث واجهات برمجة التطبيقات للإعلانات التي تضم مكافآت وواجهات برمجة التطبيقات للإعلانات البينية من أجل توافقها مع جميع أشكال الإعلانات التي يتم عرضها بملء الشاشة.
  • تمت إزالة ميزات الارتباط.
دورات تدريبية واجهة برمجة التطبيقات v19.5.0 v20.0.0 API Notes
AdSize getportraitBannerAdSizeWithحمام() getportraitAnchoredAdaptiveBannerAdSize()
getscapeBannerAdSizeWithحمام() getscapeAnchoredAdaptiveBannerAdSize()
getCurrentOrientationBannerAdSizeWithحمام() getCurrentOrientationAnchoredAdaptiveBannerAdSize()
MobileAds originize(Context, String) MobileAds.previousize(Context, OnFormatizationCompleteمستمع) تم ضبط رقم تعريف التطبيق الآن في ملف AndroidManifest.xml.
originize(Context, String, MobileAds.Settings) firstize(Context, OnFormatizationCompleteمستمع) تم إيقاف فئة "الإعدادات" نهائيًا.
getRewardedVideoAdInstance() تمت إزالتها يمكنك استخدام RewardedAd API بدلاً من ذلك.
AdListener onAdFailedToLoad(int) onAdتعذّر تحميل(LoadAdError)
onAdLeftApplication() تمت إزالتها وتستخدم أشكال الإعلانات بملء الشاشة ملء الشاشة الكاملة للمكالمة بدلاً من AdListener، ولا تتوفّر طريقة مماثلة في FullscreenContentCallback. تمت إزالة الطريقة من AdListener.
VideoController getAspectRatio() MediaContent.getAspectRatio()
AdRequest getGender() تمت إزالتها
getBirthday() تمت إزالتها
getNetworkExtras() تمت إزالتها
setنيوجهاتEnabled() تمت إزالتها
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) يستخدم الإعلان بمكافأة الآن منهج التحميل الثابت نفسه الذي يستخدمه أشكال الإعلانات الأخرى بملء الشاشة.
loadAd(PublisherAdRequest, RewardedAdLoadCallback) RewardedAd.load(Context, String, AdManagerAdRequest, RewardedAdLoadCallback)
isLoaded() تمت إزالتها توفِّر طريقة معاودة الاتصال من طريقة التحميل الثابتة إعلانًا سبق أن تم تحميله.
show(النشاط, RewardedAdCallback) show(Activity, OnUserExploreedRewardListener) تلتزم طريقة العرض هذه بأسلوب ملء الشاشة الأوسع نطاقًا.
RewardedAdLoadCallback onRewardedAdتعذّر تحميل(int) onAdتعذّر تحميل(LoadAdError)
onRewardedAdتعذّر تحميل(LoadAdError) onAdتعذّر تحميل(LoadAdError)
onRewardedAdLoaded() onAdLoaded(RewardedAd)
AppOpenAdLoadCallback onAppOpenAdتعذّر تحميل(int) onAdتعذّر تحميل(LoadAdError)
onAppOpenAdتعذّر تحميل(LoadAdError) onAdتعذّر تحميل(LoadAdError)
onAppOpenAdLoaded(AppOpenAd) onAdLoaded(AppOpenAd)
مكافآت بينيAdLoadمن معاودة الاتصال onRewardedInterstitialAdتعذّر تحميل(int) onAdتعذّر تحميل(LoadAdError)
onمكافأةedInterstitialAdتعذّر تحميل(LoadAdError) onAdتعذّر تحميل(LoadAdError)
onRewardedInterstitialAdLoaded(RewardedInterstitialAd) onAdLoaded(RewardedInterstitialAd)
InterstitialAd new InterstitialAd() InterstitialAd.load(Context, String, AdRequest, InterstitialAdLoadCallback) يستخدم الإعلان البيني الآن أسلوب التحميل الثابت نفسه مثل الأشكال الأخرى من الإعلانات بملء الشاشة.
setAdListener()
طلب إعلان DynamicHeight getNetworkExtras() تمت إزالتها تم إيقاف الفئة NetworkExtras نهائيًا.
AdLoader forContentAd() تمت إزالتها
forAppInstallAd() تمت إزالتها
withCorrelator() تمت إزالتها
getMediationAdapterClassName() تمت إزالتها