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

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

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

الحد الأدنى لمستوى واجهة برمجة التطبيقات (API) لنظام التشغيل 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)
void MobileAds.setSameAppKeyEnabled() boolean MobileAds.putPublisherFirstPartyIdEnabled()

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

استخدام 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 المحوِّل
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 حول أمان القيم الخالية ).

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

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

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

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

  • طريقة setLocation(Location location) في فئة AdRequest.Builder التي تحدّد الموقع الجغرافي للمستخدم لأغراض استهداف التوسّط
  • طريقة getLocation() في فئة AdRequest التي تعرض معلومات setLocation(Location location) المستخدِم الاستهداف حسب الموقع الجغرافي التي تم تمريرها سابقًا إلى طريقة 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 لطلبات إعادة الاتصال بالعرض التقديمي

إزالة واجهة برمجة التطبيقات القديمة لإعلانات الفيديو التي تضم مكافآت

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

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

يسرد الجدول أدناه أسماء فئات محدّدة تم تغييرها أو إزالتها. في summary:

  • تمت إعادة تسمية معظم الفئات المرتبطة بـ 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 مُزال
Correlator مُزال
search.SearchAdRequest مُزال
واجهة AdRequest.TagForUnderAgeOfConsent مُزال
واجهة 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 لمواءمة جميع أشكال الإعلانات التي تظهر على ملء الشاشة.
  • تمت إزالة ميزات Correlator.
دورات تدريبية واجهة برمجة التطبيقات v19.5.0 واجهة برمجة التطبيقات v20.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 API بدلاً من ذلك.
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) يستخدم "الإعلان الذي يعرِض مكافأة" الآن أسلوب التحميل الثابت نفسه المستخدَم في التنسيقات الأخرى التي تظهر على ملء الشاشة.
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()‎ مُزال