نقل إصدارات حزمة SDK

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

نقل البيانات من الإصدار 24 إلى الإصدار 25

توضّح الأقسام الفرعية التالية التغييرات غير المتوافقة والاختلافات في السلوك بين رقمَي الإصدار الرئيسي 24 و25 من Google Mobile Ads SDK (Legacy).

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

بدءًا من الإصدار 25.5.0، يتطلّب Google Mobile Ads SDK (Legacy) أن تعمل جميع التطبيقات على مستوى واجهة برمجة تطبيقات Android 24 كحدّ أدنى. لتعديل مستوى واجهة برمجة التطبيقات، غيِّر قيمة minSdk في ملف build.gradle على مستوى التطبيق إلى 24 أو أعلى.

إزالة عمليات معاودة الاتصال التي تم إيقافها نهائيًا

تمت إزالة عمليات معاودة الاتصال المتوقّفة نهائيًا للإعلانات من الفئات التالية:

تغييرات في واجهات برمجة التطبيقات الخاصة بحجم إعلانات البانر التكيّفية الثابتة

يؤدي الإصدار 25.0.0 إلى إيقاف واجهات برمجة التطبيقات الحالية الخاصة بأحجام إعلانات البانر التكيُّفية الثابتة، ويقدّم واجهات برمجة تطبيقات خاصة بأحجام إعلانات البانر التكيُّفية الثابتة الكبيرة. يمكن Google Mobile Ads SDK (Legacy) عرض طلبات إعلانات الفيديو على إعلانات البانر باستخدام واجهات برمجة التطبيقات الجديدة الخاصة بحجم "إعلانات البانر التكيُّفية الثابتة الكبيرة".

يوضّح الجدول التالي تفاصيل واجهات برمجة التطبيقات المتوقّفة نهائيًا لتحديد الحجم والبدائل المتاحة لها:

إزالة الصف mediation.VersionInfo

تمت إزالة فئة VersionInfo في حزمة com.google.android.gms.ads.mediation. استخدِم حزمة com.google.android.gms.ads.VersionInfo بدلاً من ذلك.

إزالة طريقة getConfiguration() في الفئة RtbSignalData

تمت إزالة طريقة getConfiguration() API المتوقّفة نهائيًا في RtbSignalData. بدلاً من ذلك، استخدِم طريقة getConfigurations() التي تعرض قائمة List<MediationConfiguration>.

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

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

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

بدءًا من الإصدار 24.0.0، تتطلّب Google Mobile Ads SDK (Legacy) أن تعمل جميع التطبيقات على المستوى 23 من واجهة برمجة التطبيقات 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 بدلاً من ذلك.

ضبط مَعلمات الاستهداف المخصّص

لضبط استهداف مخصّص في طلب عرض الإعلان، استخدِم addCustomTargeting().

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

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

تبسيط عملية معاودة الاتصال بالمكافأة لمحوّلات التوسّط

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

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

الصفوف التي تمت إزالتها

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

• DynamicHeightSearchAdRequest
• SearchAdRequest
• SearchAdView

تمت إزالة الطرق

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

الإجراءات المتوقّفة نهائيًا

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

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

توضّح الأقسام الفرعية التالية التغييرات غير المتوافقة والاختلافات في السلوك بين رقمَي الإصدار الرئيسيين 22 و23 من Google Mobile Ads SDK (Legacy).

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

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

يمكن ربط طرق AdManagerAdRequest.Builder الموروثة من الفئة الفائقة

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

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

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

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

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

توضّح الفقرات الفرعية التالية التغييرات التي قد تؤدي إلى عطل والاختلافات في السلوك بين رقمَي الإصدار الرئيسي 21 و22 من Google Mobile Ads SDK (Legacy).

استخدِم MobileAds.getVersion() للحصول على الإصدار Google Mobile Ads SDK (Legacy)

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

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

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

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

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

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

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

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

توضّح الأقسام الفرعية التالية التغييرات غير المتوافقة والاختلافات في السلوك بين رقمَي الإصدار الرئيسي 20 و21 من Google Mobile Ads SDK (Legacy):

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

اعتبارًا من الإصدار 21.0.0، يتطلّب تطبيق Google Mobile Ads SDK (Legacy) أن تعمل جميع التطبيقات على الحد الأدنى من مستوى واجهة برمجة التطبيقات 19 في Android. لضبط مستوى واجهة برمجة التطبيقات، غيِّر قيمة 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 بيانات الموقع الجغرافي لاستهداف الإعلانات. عليك استخدام واجهات برمجة التطبيقات التابعة لجهات خارجية لتوفير المعلومات لشبكات المواقع الإعلانية التابعة لجهات خارجية إذا كان ذلك مطلوبًا.

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

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

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

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

نقل البيانات من الإصدار 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.

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

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

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

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.

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

يسرد الجدول التالي التغييرات المحدّدة في الإصدار 20.0.0:

• تمت إزالة طرق الإعداد القديمة من فئة MobileAds.
• تمت إزالة بعض الطرق من فئة AdRequest.Builder() أو نقلها إلى فئة RequestConfiguration.
• تم تعديل واجهتَي برمجة التطبيقات RewardedAd وInterstitialAd لتتوافقا مع جميع أشكال الإعلانات بملء الشاشة.
• تمت إزالة ميزات أداة الربط.