本頁面由 Cloud Translation API 翻譯而成。

使用 ModuleInstallClient 確保 API 可用性

如「Google Play 服務總覽」一文所述一文：採用 Google Play 服務支援的 SDK 是由裝置端服務提供支援並安裝在 Google 認證的 Android 裝置上為了保存安裝在大量裝置中時，有些服務會視需要安裝特定裝置需要相關功能才能使用例如： ML Kit 提供在 Google Play 服務中使用模型時特別實用

最常見的情況是下載取決於 SDK 的 AndroidManifest.xml。如要進一步控管可讓您明確檢查模組的可用性、要求模組安裝、監控要求狀態及處理錯誤。

請按照下列步驟，使用 ModuleInstallClient 確保 API 可用性。請注意，下方的程式碼片段使用 TensorFlow Lite SDK (play-services-tflite-java) 做為範例程式庫，但以下步驟適用於任何與 OptionalModuleApi 整合的程式庫。這個隨著更多 SDK 支援，更新指南也會提供額外資訊。

事前準備

如要讓應用程式做好準備，請完成下列各節的步驟。

應用程式必要條件

請確認應用程式的版本檔案使用下列的值：

minSdkVersion 19 以上版本

設定應用程式

在頂層 settings.gradle 檔案中納入 Google 的 Maven 存放區和 Maven 中央存放區 dependencyResolutionManagement 區塊：
```
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}
```

在模組的 Gradle 建構檔案 (通常是 app/build.gradle) 中新增 play-services-base 和的 Google Play 服務依附元件 play-services-tflite-java:

dependencies {
  implementation 'com.google.android.gms:play-services-base:18.5.0'
  implementation 'com.google.android.gms:play-services-tflite-java:16.2.0-beta02'
}

檢查模組可用性

取得 ModuleInstallClient 的例項：

Kotlin

val moduleInstallClient = ModuleInstall.getClient(context)

Java

ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

使用 OptionalModuleApi 檢查選用模組的可用性：

Kotlin

val optionalModuleApi = TfLite.getClient(context)
moduleInstallClient
  .areModulesAvailable(optionalModuleApi)
  .addOnSuccessListener {
    if (it.areModulesAvailable()) {
      // Modules are present on the device...
    } else {
      // Modules are not present on the device...
    }
  }
  .addOnFailureListener {
    // Handle failure...
  }

Java

OptionalModuleApi optionalModuleApi = TfLite.getClient(context);
moduleInstallClient
    .areModulesAvailable(optionalModuleApi)
    .addOnSuccessListener(
        response -> {
          if (response.areModulesAvailable()) {
            // Modules are present on the device...
          } else {
            // Modules are not present on the device...
          }
        })
    .addOnFailureListener(
        e -> {
          // Handle failure…
        });

傳送延遲安裝要求

取得 ModuleInstallClient 的例項：

Kotlin

val moduleInstallClient = ModuleInstall.getClient(context)

Java

ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

傳送延遲要求：

Kotlin

val optionalModuleApi = TfLite.getClient(context)
moduleInstallClient.deferredInstall(optionalModuleApi)

Java

OptionalModuleApi optionalModuleApi = TfLite.getClient(context);
moduleInstallClient.deferredInstall(optionalModuleApi);

傳送緊急模組安裝要求

取得 ModuleInstallClient 的例項：

Kotlin

val moduleInstallClient = ModuleInstall.getClient(context)

Java

ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

(選用) 建立 InstallStatusListener 來處理安裝狀態更新。

要在自訂的使用者介面中監控下載進度 (適用於例如進度列)，您可以建立 InstallStatusListener 更新安裝狀態。

Kotlin

inner class ModuleInstallProgressListener : InstallStatusListener {
  override fun onInstallStatusUpdated(update: ModuleInstallStatusUpdate) {
    // Progress info is only set when modules are in the progress of downloading.
    update.progressInfo?.let {
      val progress = (it.bytesDownloaded * 100 / it.totalBytesToDownload).toInt()
      // Set the progress for the progress bar.
      progressBar.setProgress(progress)
    }

    if (isTerminateState(update.installState)) {
      moduleInstallClient.unregisterListener(this)
    }
  }

  fun isTerminateState(@InstallState state: Int): Boolean {
    return state == STATE_CANCELED || state == STATE_COMPLETED || state == STATE_FAILED
  }
}

val listener = ModuleInstallProgressListener()

Java

static final class ModuleInstallProgressListener implements InstallStatusListener {
    @Override
    public void onInstallStatusUpdated(ModuleInstallStatusUpdate update) {
      ProgressInfo progressInfo = update.getProgressInfo();
      // Progress info is only set when modules are in the progress of downloading.
      if (progressInfo != null) {
        int progress =
            (int)
                (progressInfo.getBytesDownloaded() * 100 / progressInfo.getTotalBytesToDownload());
        // Set the progress for the progress bar.
        progressBar.setProgress(progress);
      }
      // Handle failure status maybe…

      // Unregister listener when there are no more install status updates.
      if (isTerminateState(update.getInstallState())) {

        moduleInstallClient.unregisterListener(this);
      }
    }

    public boolean isTerminateState(@InstallState int state) {
      return state == STATE_CANCELED || state == STATE_COMPLETED || state == STATE_FAILED;
    }
  }

InstallStatusListener listener = new ModuleInstallProgressListener();

設定 ModuleInstallRequest，並將 OptionalModuleApi 新增至要求：

Kotlin

val optionalModuleApi = TfLite.getClient(context)
val moduleInstallRequest =
  ModuleInstallRequest.newBuilder()
    .addApi(optionalModuleApi)
    // Add more APIs if you would like to request multiple optional modules.
    // .addApi(...)
    // Set the listener if you need to monitor the download progress.
    // .setListener(listener)
    .build()

Java

OptionalModuleApi optionalModuleApi = TfLite.getClient(context);
ModuleInstallRequest moduleInstallRequest =
    ModuleInstallRequest.newBuilder()
        .addApi(optionalModuleApi)
        // Add more API if you would like to request multiple optional modules
        //.addApi(...)
        // Set the listener if you need to monitor the download progress
        //.setListener(listener)
        .build();

傳送安裝要求：

Kotlin

moduleInstallClient
  .installModules(moduleInstallRequest)
  .addOnSuccessListener {
    if (it.areModulesAlreadyInstalled()) {
      // Modules are already installed when the request is sent.
    }
  }
  .addOnFailureListener {
    // Handle failure…
  }

Java

moduleInstallClient.installModules(moduleInstallRequest)
    .addOnSuccessListener(
        response -> {
          if (response.areModulesAlreadyInstalled()) {
            // Modules are already installed when the request is sent.
          }
        })
    .addOnFailureListener(
        e -> {
          // Handle failure...
        });

使用 `FakeModuleInstallClient` 進行本機測試

Google Play 服務 SDK 提供的 FakeModuleInstallClient，可讓您使用依附元件模擬測試中的模組安裝 API 結果插入內容

應用程式必要條件

設定應用程式以使用 Hilt 依附元件插入架構。

在測試中將 `ModuleInstallClient` 替換為 `FakeModuleInstallClient`

新增依附元件：

在模組的 Gradle 建構檔案 (通常是 app/build.gradle) 中新增以下項目中適用於「play-services-base-testing」的 Google Play 服務依附元件：測試。
```
  dependencies {
    // other dependencies...

    testImplementation 'com.google.android.gms:play-services-base-testing:16.1.0'
  }
```

建立 Hilt 模組以提供 ModuleInstallClient：

Kotlin

@Module
@InstallIn(ActivityComponent::class)
object ModuleInstallModule {

  @Provides
  fun provideModuleInstallClient(
    @ActivityContext context: Context
  ): ModuleInstallClient = ModuleInstall.getClient(context)
}

Java

@Module
@InstallIn(ActivityComponent.class)
public class ModuleInstallModule {
  @Provides
  public static ModuleInstallClient provideModuleInstallClient(
    @ActivityContext Context context) {
    return ModuleInstall.getClient(context);
  }
}

在活動中插入 ModuleInstallClient：

Kotlin

@AndroidEntryPoint
class MyActivity: AppCompatActivity() {
  @Inject lateinit var moduleInstallClient: ModuleInstallClient

  ...
}

Java

@AndroidEntryPoint
public class MyActivity extends AppCompatActivity {
  @Inject ModuleInstallClient moduleInstallClient;

  ...
}

替換測試中的繫結：

Kotlin

@UninstallModules(ModuleInstallModule::class)
@HiltAndroidTest
class MyActivityTest {
  ...
  private val context:Context = ApplicationProvider.getApplicationContext()
  private val fakeModuleInstallClient = FakeModuleInstallClient(context)
  @BindValue @JvmField
  val moduleInstallClient: ModuleInstallClient = fakeModuleInstallClient

  ...
}

Java

@UninstallModules(ModuleInstallModule.class)
@HiltAndroidTest
class MyActivityTest {
  ...
  private static final Context context = ApplicationProvider.getApplicationContext();
  private final FakeModuleInstallClient fakeModuleInstallClient = new FakeModuleInstallClient(context);
  @BindValue ModuleInstallClient moduleInstallClient = fakeModuleInstallClient;

  ...
}

模擬模組可用性

Kotlin

@Test
fun checkAvailability_available() {
  // Reset any previously installed modules.
  fakeModuleInstallClient.reset()

  val availableModule = TfLite.getClient(context)
  fakeModuleInstallClient.setInstalledModules(api)

  // Verify the case where modules are already available...
}

@Test
fun checkAvailability_unavailable() {
  // Reset any previously installed modules.
  fakeModuleInstallClient.reset()

  // Do not set any installed modules in the test.

  // Verify the case where modules unavailable on device...
}

@Test
fun checkAvailability_failed() {
  // Reset any previously installed modules.
  fakeModuleInstallClient.reset()

  fakeModuleInstallClient.setModulesAvailabilityTask(Tasks.forException(RuntimeException()))

  // Verify the case where an RuntimeException happened when trying to get module's availability...
}

Java

@Test
public void checkAvailability_available() {
  // Reset any previously installed modules.
  fakeModuleInstallClient.reset();

  OptionalModuleApi optionalModuleApi = TfLite.getClient(context);
  fakeModuleInstallClient.setInstalledModules(api);

  // Verify the case where modules are already available...
}

@Test
public void checkAvailability_unavailable() {
  // Reset any previously installed modules.
  fakeModuleInstallClient.reset();

  // Do not set any installed modules in the test.

  // Verify the case where modules unavailable on device...
}

@Test
public void checkAvailability_failed() {
  fakeModuleInstallClient.setModulesAvailabilityTask(Tasks.forException(new RuntimeException()));

  // Verify the case where an RuntimeException happened when trying to get module's availability...
}

模擬延遲安裝要求的結果

Kotlin

@Test
fun deferredInstall_success() {
  fakeModuleInstallClient.setDeferredInstallTask(Tasks.forResult(null))

  // Verify the case where the deferred install request has been sent successfully...
}

@Test
fun deferredInstall_failed() {
  fakeModuleInstallClient.setDeferredInstallTask(Tasks.forException(RuntimeException()))

  // Verify the case where an RuntimeException happened when trying to send the deferred install request...
}

Java

@Test
public void deferredInstall_success() {
  fakeModuleInstallClient.setDeferredInstallTask(Tasks.forResult(null));

  // Verify the case where the deferred install request has been sent successfully...
}

@Test
public void deferredInstall_failed() {
  fakeModuleInstallClient.setDeferredInstallTask(Tasks.forException(new RuntimeException()));

  // Verify the case where an RuntimeException happened when trying to send the deferred install request...
}

模擬緊急安裝要求的結果

Kotlin

@Test
fun installModules_alreadyExist() {
  // Reset any previously installed modules.
  fakeModuleInstallClient.reset();

  OptionalModuleApi optionalModuleApi = TfLite.getClient(context);
  fakeModuleInstallClient.setInstalledModules(api);

  // Verify the case where the modules already exist when sending the install request...
}

@Test
fun installModules_withoutListener() {
  // Reset any previously installed modules.
  fakeModuleInstallClient.reset();

  // Verify the case where the urgent install request has been sent successfully...
}

@Test
fun installModules_withListener() {
  // Reset any previously installed modules.
  fakeModuleInstallClient.reset();

  // Generates a ModuleInstallResponse and set it as the result for installModules().
  val moduleInstallResponse = FakeModuleInstallUtil.generateModuleInstallResponse()
  fakeModuleInstallClient.setInstallModulesTask(Tasks.forResult(moduleInstallResponse))

  // Verify the case where the urgent install request has been sent successfully...

  // Generates some fake ModuleInstallStatusUpdate and send it to listener.
  val update = FakeModuleInstallUtil.createModuleInstallStatusUpdate(
    moduleInstallResponse.sessionId, STATE_COMPLETED)
  fakeModuleInstallClient.sendInstallUpdates(listOf(update))

  // Verify the corresponding updates are handled correctly...
}

@Test
fun installModules_failed() {
  fakeModuleInstallClient.setInstallModulesTask(Tasks.forException(RuntimeException()))

  // Verify the case where an RuntimeException happened when trying to send the urgent install request...
}

Java

@Test
public void installModules_alreadyExist() {
  // Reset any previously installed modules.
  fakeModuleInstallClient.reset();

  OptionalModuleApi optionalModuleApi = TfLite.getClient(context);
  fakeModuleInstallClient.setInstalledModules(api);

  // Verify the case where the modules already exist when sending the install request...
}

@Test
public void installModules_withoutListener() {
  // Reset any previously installed modules.
  fakeModuleInstallClient.reset();

  // Verify the case where the urgent install request has been sent successfully...
}

@Test
public void installModules_withListener() {
  // Reset any previously installed modules.
  fakeModuleInstallClient.reset();

  // Generates a ModuleInstallResponse and set it as the result for installModules().
  ModuleInstallResponse moduleInstallResponse =
      FakeModuleInstallUtil.generateModuleInstallResponse();
  fakeModuleInstallClient.setInstallModulesTask(Tasks.forResult(moduleInstallResponse));

  // Verify the case where the urgent install request has been sent successfully...

  // Generates some fake ModuleInstallStatusUpdate and send it to listener.
  ModuleInstallStatusUpdate update = FakeModuleInstallUtil.createModuleInstallStatusUpdate(
      moduleInstallResponse.getSessionId(), STATE_COMPLETED);
  fakeModuleInstallClient.sendInstallUpdates(ImmutableList.of(update));

  // Verify the corresponding updates are handled correctly...
}

@Test
public void installModules_failed() {
  fakeModuleInstallClient.setInstallModulesTask(Tasks.forException(new RuntimeException()));

  // Verify the case where an RuntimeException happened when trying to send the urgent install request...
}

使用 ModuleInstallClient 確保 API 可用性

事前準備

應用程式必要條件

設定應用程式

檢查模組可用性

Kotlin

Java

Kotlin

Java

傳送延遲安裝要求

Kotlin

Java

Kotlin

Java

傳送緊急模組安裝要求

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

使用 FakeModuleInstallClient 進行本機測試

應用程式必要條件

在測試中將 ModuleInstallClient 替換為 FakeModuleInstallClient

Kotlin

Java

Kotlin

Java

Kotlin

Java

模擬模組可用性

Kotlin

Java

模擬延遲安裝要求的結果

Kotlin

Java

模擬緊急安裝要求的結果

Kotlin

Java

使用 `FakeModuleInstallClient` 進行本機測試

在測試中將 `ModuleInstallClient` 替換為 `FakeModuleInstallClient`