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

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

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

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

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

يمكن ربط طرق AdManagerAdRequest.Builder المكتسَبة من الفئة الأساسية

في الإصدار 23.0.0، يمكن ربط طرق AdManagerAdRequest.Builder المكتسبة من المؤسسة الرئيسية معًا لإنشاء AdManagerAdRequest باستخدام طلب واحد:

Java

AdManagerAdRequest request = new AdManagerAdRequest.Builder()
    .addCustomTargeting("age", "25") // AdManagerAdRequest.Builder method.
    .setContentUrl("https://www.example.com") // Method inherited from parent.
    .build(); // Builds an AdManagerAdRequest.

Kotlin

var request = AdManagerAdRequest.Builder()
  .addCustomTargeting("age", "25") // AdManagerAdRequest.Builder method.
  .setContentUrl("https://www.example.com") // Method inherited from parent.
  .build() // Builds an AdManagerAdRequest.

طرق الاستخدام المتوقفة نهائيًا التي تمت إزالتها أو استبدالها

واجهة برمجة التطبيقات 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() الجديدة لحزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة.

إزالة NativeCustomFormatAd.getVideoMediaView() المتوقّف نهائيًا

في الإصدار 21، وفّرت لك حزمة SDK لإعلانات Google على الأجهزة الجوّالة طريقة NativeCustomFormatAd.getVideoMediaView() للحصول على مادة عرض الوسائط لتنسيق إعلان مخصّص مدمج.

اعتبارًا من الإصدار 22، يمكنك إنشاء MediaView وضبط محتوى الوسائط فيه، واستخدام MediaContent.getVideoController() للحصول على عناصر التحكّم في الفيديو.

v22

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

v21

// 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.

الإصدار 21.0.0 الإصدار 22.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)
  • تمثّل هذه السمة طريقة getLocation() في الفئة MediationAdConfiguration والتي تعرض الموقع الجغرافي للمستخدم، إذا تم تحديده من خلال AdRequest.

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

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

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

يتم إيقاف جميع واجهات الأحداث المخصصة لصالح الفئة Adapter وواجهة MediationAdLoadCallback.

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

واجهات الإصدار 20.0.0 فئة/ واجهة الإصدار 21.0.0
CustomEvent المحوِّل
CustomEventBanner
CustomEventInterstitial
CustomEventNative
CustomEventBannerListener محوِّل، 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 مُزال
الموصّل مُزال
search.SearchAdRequest مُزال
واجهة AdRequest.TagForAgeOfConsent مُزال
واجهة 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. باختصار:

  • تمت إزالة طرق الإعداد القديمة من فئة إعلانات الأجهزة الجوّالة.
  • تمّت إزالة بعض الطُرق من فئة AdRequest.Builder() أو نقلها إلى فئة RequestConfiguration.
  • تم تعديل واجهات برمجة التطبيقات للإعلانات التي تضم مكافآت وإعلانات بينية لتتوافق مع جميع أشكال الإعلانات التي تظهر بملء الشاشة.
  • تمت إزالة ميزات Correlator.
دورات تدريبية واجهة برمجة التطبيقات v19.5.0 واجهة برمجة التطبيقات v20.0.0 ملاحظات
AdSize getPortraitBannerAdSizeWithWidth() getPortraitAnchoredAdaptiveBannerAdSize()
getLandscapeBannerAdSizeWithWidth() getLandscapeAnchoredAdaptiveBannerAdSize()
getCurrentOrientationBannerAdSizeWithWidth() getCurrentOrientationAnchoredAdaptiveBannerAdSize()
MobileAds initialize(Context, String) MobileAds.initialize(Context, OnInitializationCompleteListener) يتم الآن ضبط رقم تعريف التطبيق في AndroidManifest.xml.
تهيئة(السياق، السلسلة، إعدادات الجوال) تهيئة(Context, OnInitializationCompleteListener) تم إيقاف فئة "الإعدادات" نهائيًا.
getRewardedVideoAdInstance() مُزال يمكنك استخدام واجهة برمجة التطبيقات BonusedAd API بدلاً من ذلك.
AdListener onAdFailedToLoad(int) onAdFailedToLoad(LoadAdError)
onAdLeftApplication() مُزال تستخدم أشكال الإعلانات بملء الشاشة ميزة FullscreenContentCallback بدلاً من AdListener، ولا تتوفر طريقة مكافئة في FullscreenContentCallback. تمت إزالة الطريقة من AdListener.
VideoController getAspectRatio() MediaContent.getAspectRatio()
PublisherAdRequest getGender() مُزال
getBirthday() مُزال
getNetworkExtras() مُزال
setManualImpressionsEnabled() مُزال
updateCorrelator() مُزال راجِع فلترة محتوى الإعلانات.
PublisherAdRequest.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, BonusedAdLoadCallback) 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)
PublisherInterstitialAd new PublisherInterstitialAd() InterstitialAd.load(Context, String, AdRequest, InterstitialAdLoadCallback) يستخدم InterstitialAd الآن أسلوب التحميل الثابت نفسه المستخدَم في أشكال الإعلانات الأخرى التي تظهر على ملء الشاشة.
setAdListener()
DynamicHeightSearchAdRequest getNetworkExtras() مُزال تم إيقاف فئة NetworkExtras نهائيًا.
AdLoader forContentAd() مُزال
forAppInstallAd() مُزال
withCorrelator() مُزال
getMediationAdapterClassName() مُزال