دليل نقل حزمة تطوير البرامج (SDK) لنظام التشغيل Android 5.0

يوضّح هذا الدليل التغييرات اللازمة للانتقال إلى الإصدار 5.0.

تحديثات نظام Gradle والمكوّن الإضافي لنظام Gradle المتوافق مع Android

ترقية إصدارات Gradle و"المكوّن الإضافي لنظام Gradle المتوافق مع Android"

عليك أولاً ترقية إصدارَي Gradle و"المكوّن الإضافي لنظام Gradle المتوافق مع Android". يتضمّن هذا التحديث توافقًا أفضل مع بعض التبعيات في حزمة تطوير البرامج (SDK) (بما في ذلك Kotlin 1.9)، بالإضافة إلى بعض إصلاحات الأخطاء البالغة الأهمية.

يتطلّب هذا الإصدار الرئيسي من حزمة تطوير البرامج (SDK) ما يلي من ملحقات الإصدار لمشروع تطبيق Android:

• الإصدار 7.5.0 من Gradle على الأقل، ولكن ليس أعلى من الإصدار 7.6.0
• إصدار من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) في النطاق v7.4.x.

يمكنك استهداف إصدار أعلى من المكوّنات الإضافية، ولكن قد تظهر لك تحذيرات بشأن الإيقاف النهائي، أو قد لا تعمل بعض الميزات الجديدة.

لتعديل إصدار Gradle، عدِّل السطر في ملف /gradle/wrapper/gradle-wrapper.properties الخاص بمشروعك.

distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-all.zip

لتعديل إصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android، عدِّل ملف build.gradle الذي يحتوي على كتلة buildscript. على سبيل المثال:

buildscript {
    repositories {
        google()
        mavenCentral()
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:7.4.1'
    }
}

نقل البيانات من Java 7 إلى Java 8

الخطوة 1: تفعيل إمكانية استخدام مكتبة Java 8

المصدر

بما أنّ الحد الأدنى لمستوى واجهة برمجة التطبيقات لحزمة تطوير البرامج (SDK) هو 23 وإصدار "مكوّن Android الإضافي" المطلوب هو 7.4 أو إصدار أحدث، يختلف الإعداد قليلاً عن مستندات المصدر المذكورة.

buildscript {

    repositories {
        google()
        mavenCentral()
        jcenter()
        maven {
            url = uri("https://storage.googleapis.com/r8-releases/raw")
        }
    }
    dependencies {
        classpath 'com.android.tools:r8:8.0.46'
        classpath 'com.android.tools.build:gradle:7.4.1'
    }
}

android {
    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs_nio:2.0.3'
}

ملاحظة: لا يتيح هذا النص البرمجي استخدام مكتبة Java 8 فحسب، بل يتيح أيضًا استخدام مكتبات Java 8 والإصدارات الأحدث. ويجب توفّر كليهما لاستخدام أحدث إصدارات من حزمتَي تطوير البرامج (SDK) الخاصة بالمستهلكين والسائقين.

الخطوة 2: نقل البيانات من Proguard أو Dexguard إلى R8

R8، المصدر

يستخدم الإصدار 7.4 من "مكوّن Android الإضافي في Gradle" أو الإصدارات الأحدث أداة R8 كأداة تلقائية لتقليل حجم الرمز البرمجي وتشويشه وتحسينه للثنائي، لذلك لا يلزم اتّخاذ أي إجراء خاص في هذه المرحلة.

إذا تم نقل المشروع من الإصدار 4.0 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android، قد يصدر المكوّن الإضافي لنظام Gradle المتوافق مع Android التحذيرات التالية بشأن عمليات إزالة الملفات:

• استخدام useProguard true في ملف build.gradle
• استخدام android.enableR8=false في ملف gradle.properties

تؤدي إزالة هذه الأسطر عادةً إلى حلّ هذه المشاكل.

نقل البيانات من Kotlin 1.6 إلى 1.9

الخطوة 1: الانتقال إلى الإصدار 1.9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Kotlin

المصدر

عدِّل إصدار المكوّن الإضافي Kotlin Gradle في ملف build.gradle الخاص بالوحدة ذات المستوى الأعلى في تطبيقك. تأكَّد من إضافة org.jetbrains.kotlin:kotlin-gradle-plugin في العناصر التابعة من قسم buildscript في حال عدم توفّره.

buildscript {
  dependencies {
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0"
  }
}

يجب نقل تطبيقك من Kotlin-synthetics إذا كنت تستخدم الإصدار 1.6.X أو 1.7.X من إضافة Kotlin Gradle. راجِع دليل نقل البيانات الرسمي للاطّلاع على مزيد من المعلومات.

الخطوة 2: ترقية kotlin-stdlib إلى الإصدار 1.9.0

المصدر

رقِّي الإصدار kotlin-stblib إلى 1.9.0 في ملف build.gradle الخاص بتطبيقك.

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.0"
}

احرص على إزالة أي إشارات إلى kotlin-stdlib-jdk7 أو kotlin-stdlib-jdk8. تم دمج كلتا التبعيتَين في kotlin-stdlib بدءًا من Kotlin 1.8.0.

إيقاف StatusListener نهائيًا

تم إيقاف واجهة StatusListener نهائيًا (ستتم إزالتها في الإصدار 6)، وسيتم استخدام DriverStatusListener بدلاً منها.

هناك 3 تغييرات رئيسية:

1. غيِّر واجهة implements من StatusListener إلى DriverStatusListener.
2. أضِف المَعلمة Nullable cause إلى updateStatus.
3. اتّصِل بالرقم DriverContextBuilder.setDriverStatusListener بدلاً من setStatusListener.

تتشارك DriverStatusListener البنية نفسها مع StatusListener. ويكمن الاختلاف الرئيسي بينهما في أنّ DriverStatusListener.updateStatus() تأخذ مَعلمة إضافية باسم cause. يقدّم هذا الإجراء للمستخدمين إحصاءات حول سبب ظهور حالة الخطأ عند إجراء تعديل.

عادةً، يمكنك استخدام cause لاسترداد رمز الخطأ الذي تعرضه Fleet Engine عند تعذُّر تعديل الموقع الجغرافي.

يوضّح المثال التالي كيفية تنفيذ StatusListener:

class MyStatusListener implements StatusListener {
  /** Called when background status is updated during actions such as location reporting. */
  @Override
  public void updateStatus(
      StatusLevel statusLevel, StatusCode statusCode, String statusMsg) {
    // Implementation
  }
}

// Inject StatusListener into DriverContext.
DriverContextBuilder.setStatusListener(new MyStatusListener());

يوضّح ما يلي نموذجًا لعملية تنفيذ DriverStatusListener:

class MyStatusListener implements DriverStatusListener {
  /** Called when background status is updated during actions such as location reporting. */
  @Override
  public void updateStatus(
      StatusLevel statusLevel, StatusCode statusCode, String statusMsg, @Nullable Throwable cause) {
    // Existing implementation

    if (cause != null && cause instanceof StatusRuntimeException) {
      if (Status.NOT_FOUND.getCode().equals(cause.getStatus().getCode())) {
        // NOT_FOUND gRPC exception thrown by Fleet Engine.
      }
    }
  }
}

DriverContextBuilder.setStatusListener(new MyStatusListener());

تنفيذ DriverStatusListener كواجهة وظيفية

يتوافق DriverStatusListener مع واجهات Java الوظيفية تمامًا مثل الإصدار السابق. في ما يلي مثال على ذلك:

DriverContextBuilder.setDriverStatusListener((statusLevel, statusCode, statusMsg, cause) -> {
  if (cause != null && cause instanceof StatusRuntimeException) {
    if (Status.NOT_FOUND.getCode().equals(cause.getStatus().getCode())) {
      // NOT_FOUND gRPC exception thrown by Fleet Engine.
    }
  }
});