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

使用 ModuleInstallClient 確保 API 可用性

如「Google Play 服務簡介」一文所述，Google Play 服務支援的 SDK 會在 Google 認證 Android 裝置上，透過裝置端服務提供支援。為節省整個裝置機隊的儲存空間和記憶體，系統會在特定裝置需要相關功能時，視需要安裝部分服務。舉例來說，在 Google Play 服務中使用模型時，ML Kit 會提供這個選項。

最常見的情況是，服務 (或「模組」) 會根據 SDK AndroidManifest.xml 中的依附元件，與需要該服務的應用程式同時下載及安裝。為提供更多控制選項，模組安裝 API 可明確檢查模組可用性、要求模組安裝作業、監控要求狀態，以及處理錯誤。

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

事前準備

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

應用程式必要條件

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

minSdkVersion 19 以上版本

設定應用程式

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

在模組的 Gradle 版本檔案 (通常為 app/build.gradle) 中，新增 play-services-base 和 play-services-tflite-java 的 Google Play 服務依附元件：

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

檢查模組可用性

取得 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`