راهنمای انتقال کیت توسعه نرم‌افزار Android Driver نسخه ۵.۰

این راهنما تغییرات لازم برای انتقال به نسخه ۵.۰ را شرح می‌دهد.

به‌روزرسانی‌های Gradle و افزایه Android Gradle

نسخه‌های Gradle و «افزایه Android Gradle» را ارتقا دهید

ابتدا نسخه‌های Gradle و «افزایه Android Gradle» را ارتقا دهید. این ارتقا شامل سازگاری بهتر با برخی‌از وابستگی‌های کیت توسعه نرم‌افزار (ازجمله Kotlin 1.9) و همچنین چند رفع اشکال مهم است.

این نسخه اصلی کیت توسعه نرم‌افزار به وابستگی‌های نسخه زیر برای پروژه برنامه Android شما نیاز دارد:

  • نسخه Gradle حداقل v7.5.0 باشد اما بالاتر از v7.6.0 نباشد.
  • نسخه افزایه Android Gradle (AGP) در محدوده v7.4.x.

می‌توانید نسخه بالاتری از افزونه‌ها را هدف قرار دهید؛ اما ممکن است با هشدارهای منسوخ شدن مواجه شوید یا برخی‌از ویژگی‌های جدید کار نکنند.

برای اصلاح نسخه Gradle، خط را در فایل /gradle/wrapper/gradle-wrapper.properties پروژه خود اصلاح کنید

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

برای تغییر نسخه «افزایه Android Gradle»، فایل build.gradle را که شامل بلوک buildscript است تغییر دهید. برای مثال:

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

انتقال پشتیبانی کتابخانه از Java 7 به Java 8

مرحله ۱ - فعال کردن پشتیبانی کتابخانه Java 8

منبع

ازآنجایی‌که حداقل سطح میانای برنامه‌سازی کاربردی کیت توسعه نرم‌افزار ۲۳ است و نسخه AGP موردنیاز ۷.۴+ است، پیکربندی کمی با مستندات منبع ذکرشده متفاوت است.

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'
}

مرحله ۲ - انتقال از Proguard یا Dexguard به R8

R8، منبع

‫AGP نسخه ۷.۴ و بالاتر از R8 به‌عنوان ابزار پیش‌فرض کوچک‌سازی، مبهم‌سازی، و بهینه‌سازی برای باینری استفاده می‌کند، بنابراین در این مرحله نیازی به اقدام خاصی نیست.

اگر پروژه از AGP نسخه ۴.۰ یا بالاتر انتقال داده شود، AGP ممکن است هشدارهای زیر را درباره برداشتن فایل‌ها صادر کند:

  • ‫useProguard true مورد استفاده در build.gradle فایل
  • android.enableR8=false مورد استفاده در فایل gradle.properties

حذف این خطوط معمولاً این مشکلات را برطرف می‌کند.

انتقال از Kotlin 1.6 به 1.9

مرحله ۱ - انتقال به افزایه Kotlin Gradle نسخه ۱.۹.۰

منبع

نسخه «افزایه Kotlin Gradle» را در فایل build.gradle ماژول سطح بالای برنامه‌تان به‌روز کنید. حتماً org.jetbrains.kotlin:kotlin-gradle-plugin را در وابستگی‌ها از بلوک buildscript اضافه کنید، درصورتی‌که وجود نداشته باشد.

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

اگر از «افزایه Kotlin Gradle» نسخه 1.6.X یا 1.7.X استفاده می‌کنید، باید برنامه‌تان را از Kotlin-synthetics انتقال دهید. برای اطلاعات بیشتر، به راهنمای انتقال رسمی مراجعه کنید.

مرحله ۲ - ارتقا دادن kotlin-stdlib به نسخه 1.9.0

منبع

‫kotlin-stblib را در فایل build.gradle برنامه به نسخه 1.9.0 ارتقا دهید.

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

حتماً همه ارجاع‌ها به kotlin-stdlib-jdk7 یا kotlin-stdlib-jdk8 را بردارید. هر دو وابستگی در kotlin-stdlib از Kotlin 1.8.0 ادغام شده‌اند.

منسوخ شدن StatusListener

میانای StatusListener اکنون منسوخ شده است (در نسخه ۶ برداشته خواهد شد)، به‌نفع DriverStatusListener.

به‌طور کلی ۳ تغییر وجود دارد:

  1. رابط implements را از StatusListener به DriverStatusListener تغییر دهید.
  2. پارامتر Nullable cause را به updateStatus اضافه کنید.
  3. به‌جای setStatusListener، با DriverContextBuilder.setDriverStatusListener تماس بگیرید.

‫DriverStatusListener ساختاری مشابه StatusListener دارد. تفاوت اصلی بین آن‌ها این است که DriverStatusListener.updateStatus() پارامتر اضافه‌ای به نام cause می‌گیرد. این ویژگی به کاربران اطلاعات آماری درباره علت به‌روزرسانی با سطح وضعیت خطا ارائه می‌دهد.

معمولاً از cause برای بازیابی کد خطای برگشتی از «موتور ناوگان» برای به‌روزرسانی‌های مکان ناموفق استفاده می‌کنید.

نمونه زیر نحوه پیاده‌سازی 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 درست مانند نسخه قبلی‌اش از میاناهای تابعی جاوا پشتیبانی می‌کند. در اینجا نمونه‌ای از آن آورده شده است:

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