دليل نقل البيانات في حزمة تطوير البرامج (SDK) 3.0 لتطبيقات Android المخصّصة للمستهلكين
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
نقل البيانات إلى Kotlin 2.0
إذا كنت تستخدم الإصدار 3.0 أو إصدارًا أحدث من حزمة Consumer SDK لنظام التشغيل Android، عليك الترقية إلى الإصدار 2.0 من Kotlin. تقدّم هذه الصفحة إرشادات لتسهيل عملية الانتقال إلى إصدار Kotlin الجديد.
التوافق بين Gradle وAGP
يحتوي الإصدار 2.0 من Kotlin على متطلبات الحد الأدنى والأقصى
للإصدارات
من Gradle والمكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP). تأكَّد من أنّ مشروعك يستوفي هذه المتطلبات لاستخدام Kotlin 2.0.
الحد الأدنى لإصدار "مكوّن Android الإضافي Gradle" المطلوب لاستخدام الإصدار 3.0 أو الإصدارات الأحدث من Consumer SDK
يتطلّب الإصدار 3.0 من حزمة تطوير البرامج (SDK) للمستهلكين استخدام الإصدار 7.3 أو إصدار أحدث من "مكوّن Android الإضافي لنظام Gradle".
وضع R8 الكامل
لا يتيح الإصدار 3 من حزمة تطوير البرامج (SDK) المخصّصة للمستهلكين والإصدارات الأقدم وضع R8 الكامل. يجب إيقاف وضع R8 الكامل بشكل صريح إذا كان تطبيقك يستهدف الإصدار 8.0 من "مكوّن Android الإضافي لنظام Gradle" أو الإصدارات الأحدث.
#settings.gradleandroid.enableR8.fullMode=false
التوافق مع إصدارات Kotlin
تتيح لغة Kotlin التوافق مع ثلاثة إصدارات سابقة من اللغة.
هذا يعني أنّه إذا كنت تستخدم الإصدار 1.7 أو إصدارًا أحدث من Kotlin مع حزمة Consumer SDK، من المفترض أن تتمكّن من الترقية إلى الإصدار 2.0 من Kotlin بدون الحاجة إلى حلّ جميع التغييرات غير المتوافقة. ومع ذلك، لا ينطبق توافق Kotlin إلا على ميزات اللغة الثابتة.
إذا كنت تستخدم ميزات في مرحلة الإصدار الأولي أو التجريبي أو ميزات تجريبية في لغة Kotlin،
قد تحتاج إلى إجراء تغييرات إضافية عند الترقية.
يعيد هذا الخيار التغييرات غير المتوافقة إلى سلوك إصدار Kotlin السابق.
على سبيل المثال، إذا كنت تستخدم الإصدار 1.7 من Kotlin، يمكنك تحديد [ -
language-version 1.7] ولن تسري التغييرات الجديدة غير المتوافقة بعد ذلك:
android{kotlinOptions{languageVersion='1.7'}}
api-version X.Y
يمنع هذا الخيار استخدام واجهات برمجة تطبيقات جديدة قبل أن يصبح الرمز البرمجي التابع جاهزًا لدمج Kotlin 2.0.
android{kotlinOptions{apiVersion='1.7'}}
نهج أكثر استهدافًا
بالإضافة إلى استخدام علامات التوافق مع Kotlin، ننصحك بمراجعة ملاحظات إصدار Kotlin واختيار السلوكيات التي تريد الاحتفاظ بها من الإصدار الذي ستتم الترقية منه. توفّر Kotlin قائمة بالتغييرات غير المتوافقة مع الإصدارات السابقة والعلامات التي يمكن ضبطها للاحتفاظ بالسلوك الأصلي في أدلة التوافق الخاصة بكل إصدار:
تاريخ التعديل الأخير: 2025-09-04 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-09-04 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eUpgrading to Kotlin 2.0 is mandatory when utilizing the Consumer SDK for Android 3.0 or later.\u003c/p\u003e\n"],["\u003cp\u003eEnsure your Gradle and Android Gradle Plugin (AGP) versions meet the compatibility requirements for Kotlin 2.0, with Consumer SDK 3.0+ necessitating AGP 7.3 or higher.\u003c/p\u003e\n"],["\u003cp\u003eDisable Full R8 mode explicitly for Consumer SDK v3 and below when targeting AGP 8.0+.\u003c/p\u003e\n"],["\u003cp\u003eWhile Kotlin generally offers backward compatibility, potential breaking changes might require adjustments, especially when using alpha, beta, or experimental Kotlin features.\u003c/p\u003e\n"],["\u003cp\u003eLeverage Kotlin compatibility flags like \u003ccode\u003elanguage-version\u003c/code\u003e and \u003ccode\u003eapi-version\u003c/code\u003e or consult the Kotlin compatibility guides for managing specific breaking changes during the upgrade.\u003c/p\u003e\n"]]],["To migrate to Kotlin 2.0 with Consumer SDK 3.0+, ensure your Gradle and AGP versions meet Kotlin 2.0 requirements (AGP 7.3+). Disable Full R8 mode if using AGP 8.0+ by setting `android.enableR8.fullMode=false` in `settings.gradle`. Utilize Kotlin compatibility flags, `languageVersion` and `apiVersion`, to revert breaking changes or limit new API usage. Consult the Kotlin compatibility guides for specific version changes and behavior flags.\n"],null,["Migrate to Kotlin 2.0\n\nIf you are using the Consumer SDK for Android 3.0+ you must upgrade to Kotlin\n2.0. This page provides guidance to ease the transition to the new Kotlin\nversion.\n| **Note:** For information on upgrading to Kotlin 1.9, which was required for the Consumer SDK 5.0+ see the [Kotlin 1.9 upgrade\n| guide](/maps/documentation/transportation-logistics/on-demand-rides-deliveries-solution/trip-order-progress/migrations/android_consumer_sdk_v2.0_migration#kotlin_16_to_19_migration).\n\nGradle and AGP compatibility\n\nKotlin 2.0 has [requirements for the minimum and maximum\nversions](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin)\nfor your Gradle and Android Gradle Plugin (AGP) version. Ensure that your\nproject meets these requirements for Kotlin 2.0.\n\nAGP minimum version for the Consumer SDK 3.0+\n\nConsumer SDK 3.0 requires using AGP 7.3+.\n\nFull R8 mode\n\nConsumer SDK v3 and below does not support Full R8 mode. You must explicitly\ndisable Full R8 mode if your application targets AGP 8.0+. \n\n # settings.gradle\n android.enableR8.fullMode=false\n\nKotlin version compatibility\n\nKotlin supports backwards compatibility with [three previous language\nversions](https://kotlinlang.org/docs/kotlin-evolution-principles.html#compatibility-options).\nThis means that if you are already using Kotlin 1.7+ with the Consumer SDK, you\nshould be able to upgrade to Kotlin 2.0 without having to resolve all of the\nbreaking changes. However, [Kotlin compatibility only applies to stable language\nfeatures](https://kotlinlang.org/docs/components-stability.html#stability-levels-explained).\nIf you are using alpha, beta or experimental features in the Kotlin language,\nthen you may have to make additional changes when upgrading.\n\nKotlin compatibility flags\n\nAs noted in the previous section, Kotlin supports up to 3 previous versions of\nthe language when upgrading. Kotlin [supplies two flags to help with limiting\nbreaking changes](https://kotlinlang.org/docs/compatibility-modes.html):\n\nlanguage-version X.Y\n\nThis flag reverts breaking changes to the behavior of a previous Kotlin version.\nFor example, if you are using Kotlin 1.7, you could specify `[ -\nlanguage-version 1.7]` and the new breaking changes would no longer take effect: \n\n android {\n kotlinOptions {\n languageVersion = '1.7'\n }\n }\n\napi-version X.Y\n\nThis flag prevents new APIs from being used before dependent downstream code is\nready to incorporate Kotlin 2.0. \n\n android {\n kotlinOptions {\n apiVersion = '1.7'\n }\n }\n\nA more targeted approach\n\nIn addition to using Kotlin compatibility flags, we recommend reviewing the\nKotlin release notes and choosing the behaviors that you would like to retain\nfrom the version that you are upgrading from. Kotlin provides a list of breaking\nchanges and the flags that can be set to retain the original behavior in its\ncompatibility guides for each version:\n\n- [1.8 compatibility guide](https://kotlinlang.org/docs/compatibility-guide-18.html)\n- [1.9 compatibility guide](https://kotlinlang.org/docs/compatibility-guide-19.html)\n- [2.0 compatibility guide](https://kotlinlang.org/docs/compatibility-guide-20.html)"]]
