Android Driver SDK 5.0 遷移指南

本指南說明遷移至 5.0 版的必要變更。

Gradle 和 Android Gradle 外掛程式更新

升級 Gradle 和 Android Gradle 外掛程式版本

首先，請升級 Gradle 和 Android Gradle 外掛程式版本。本次升級包含改善特定 SDK 依附元件 (包括 Kotlin 1.9) 的相容性，以及一些重大錯誤修正。

這個 SDK 主要版本需要您的 Android 應用程式專案使用以下版本依附元件：

  • Gradle 版本至少為 7.5.0，但低於 7.6.0 版。
  • 位於 v7.4.x 範圍內的 Android Gradle 外掛程式 (AGP) 版本。

您可以指定較新版本的外掛程式；不過，您可能會遇到淘汰警告，或者某些新功能可能無法運作。

如要修改 Gradle 版本，請修改專案 /gradle/wrapper/gradle-wrapper.properties 檔案中的該行

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

如要修改 Android Gradle 外掛程式版本，請修改包含 buildscript 區塊的 build.gradle 檔案。例如：

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

Java 7 到 Java 8 程式庫支援遷移

步驟 1 - 啟用 Java 8 程式庫支援

資料來源

由於 SDK 最低 API 級別為 23，而必要的 AGP 版本為 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'
}

步驟 2 - 從 Proguard 或 Dexguard 遷移至 R8

R8，來源

AGP 7.4 以上版本使用 R8 做為二進位檔的預設縮減、模糊化和最佳化工具，因此目前不需要採取特殊動作。

如果專案是從 AGP 4.0 以上版本遷移，AGP 可能會發出檔案移除的以下警告：

  • build.gradle 個檔案的useProguard true用量
  • gradle.properties 個檔案的android.enableR8=false用量

移除這類行通常就能解決問題。

Kotlin 1.6 至 1.9 遷移作業

步驟 1 - 遷移至 Kotlin Gradle 外掛程式 1.9.0

資料來源

在應用程式頂層模組 build.gradle 檔案中更新 Kotlin 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 合成項目遷移應用程式。詳情請參閱官方遷移指南。

步驟 2：將 kotlin-stdlib 升級至 1.9.0

資料來源

在應用程式 build.gradle 檔案中，將 kotlin-stblib 升級至 1.9.0 版。

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

請務必移除所有的 kotlin-stdlib-jdk7 或 kotlin-stdlib-jdk8 參照。從 Kotlin 1.8.0 開始，這兩個依附元件已合併為 kotlin-stdlib。

StatusListener 已淘汰

StatusListener 介面現已淘汰 (將在 v6 中移除)，改用 DriverStatusListener。

主要有 3 項異動：

  1. 將 implements 介面從 StatusListener 變更為 DriverStatusListener。
  2. 在 updateStatus 中新增 Nullable cause 參數。
  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.
    }
  }
});