オンデマンド Google Play 開発者サービス モジュールの公開設定を管理する

Google Play 開発者サービスの概要の記事で説明されているように、Google Play 開発者サービスを搭載した SDK は、Google 認定の Android デバイスのデバイス上のサービスを利用しています。デバイス全体のストレージとメモリを節約するため、一部のサービスはモジュールとして提供され、アプリが関連する機能を必要とするときにオンデマンドでインストールされます。たとえば、Google Play 開発者サービスでモデルを使用する場合は、ML Kit でこのオプションが提供されます。

ほとんどの場合、アプリが必要な API を使用すると、Google Play 開発者サービス SDK によって必要なモジュールが自動的にダウンロードされてインストールされます。ただし、モジュールを事前にインストールしてユーザー エクスペリエンスを向上させたい場合など、プロセスをより細かく制御したい場合があります。

ModuleInstallClient API を使用すると、次のことができます。

• モジュールがデバイスにすでにインストールされているかどうかを確認します。
• モジュールのインストールをリクエストします。
• インストールの進行状況をモニタリングします。
• インストール プロセス中にエラーを処理する。

このガイドでは、ModuleInstallClient を使用してアプリ内のモジュールを管理する方法について説明します。次のコード スニペットは TensorFlow Lite SDK（play-services-tflite-java）を例として使用していますが、これらの手順は OptionalModuleApi と統合されているすべてのライブラリに適用されます。

始める前に

アプリを準備するには、以下のセクションに示す手順を完了します。

アプリの前提条件

アプリのビルドファイルで次の値が使用されていることを確認します。

• minSdkVersion が 23 以上

アプリを構成する

1. 最上位レベルの settings.gradle ファイルで、dependencyResolutionManagement ブロック内に Google の Maven リポジトリと Maven セントラル リポジトリを含めます。

   dependencyResolutionManagement {
       repositories {
           google()
           mavenCentral()
       }
   }
   

2. モジュールの Gradle ビルドファイル（通常は app/build.gradle）に、play-services-base と play-services-tflite-java の Google Play 開発者サービスの依存関係を追加します。

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

モジュールが利用可能かどうかを確認する

モジュールをインストールする前に、デバイスにすでにインストールされているかどうかを確認できます。これにより、不要なインストール リクエストを回避できます。

1. ModuleInstallClient のインスタンスを取得します。

   Kotlin

   val moduleInstallClient = ModuleInstall.getClient(context)

   Java

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

2. OptionalModuleApi を使用してモジュールの可用性を確認します。この API は、使用している Google Play 開発者サービス SDK によって提供されます。

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

延期インストールをリクエストする

モジュールをすぐに必要としない場合は、延期インストールをリクエストできます。これにより、Google Play 開発者サービスは、デバイスがアイドル状態にあり Wi-Fi に接続されているときに、バックグラウンドでモジュールをインストールできます。

1. ModuleInstallClient のインスタンスを取得します。

   Kotlin

   val moduleInstallClient = ModuleInstall.getClient(context)

   Java

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

2. 遅延リクエストを送信します。

   Kotlin

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

   Java

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

緊急のモジュール インストールをリクエストする

アプリでモジュールをすぐに必要とする場合は、緊急インストールをリクエストできます。これにより、モバイルデータを使用する場合でも、できるだけ早くモジュールをインストールしようとします。

1. ModuleInstallClient のインスタンスを取得します。

   Kotlin

   val moduleInstallClient = ModuleInstall.getClient(context)

   Java

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

2. （省略可）インストールの進行状況をモニタリングする InstallStatusListener を作成します。

   アプリの UI にダウンロードの進行状況を表示する場合（進行状況バーなど）、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();

3. ModuleInstallRequest を構成し、OptionalModuleApi をリクエストに追加します。

   Kotlin

   val optionalModuleApi = TfLite.getClient(context)
   val moduleInstallRequest =
     ModuleInstallRequest.newBuilder()
       .addApi(optionalModuleApi)
       // Add more APIs if you would like to request multiple 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 modules
           //.addApi(...)
           // Set the listener if you need to monitor the download progress
           //.setListener(listener)
           .build();

4. インストール リクエストを送信します。

   Kotlin

   moduleInstallClient
     .installModules(moduleInstallRequest)
     .addOnSuccessListener {
       if (it.areModulesAlreadyInstalled()) {
         // Modules are already installed when the request is sent.
       }
       // The install request has been sent successfully. This does not mean
       // the installation is completed. To monitor the install status, set an
       // InstallStatusListener to the ModuleInstallRequest.
     }
     .addOnFailureListener {
       // Handle failure…
     }

   Java

   moduleInstallClient.installModules(moduleInstallRequest)
       .addOnSuccessListener(
           response -> {
             if (response.areModulesAlreadyInstalled()) {
               // Modules are already installed when the request is sent.
             }
             // The install request has been sent successfully. This does not
             // mean the installation is completed. To monitor the install
             // status, set an InstallStatusListener to the
             // ModuleInstallRequest.
           })
       .addOnFailureListener(
           e -> {
             // Handle failure...
           });

FakeModuleInstallClient でアプリをテストする

Google Play 開発者サービス SDK には、依存関係挿入を使用してテストでモジュール インストール API の結果をシミュレートできる FakeModuleInstallClient が用意されています。これにより、実際のデバイスにデプロイしなくても、さまざまなシナリオでアプリの動作をテストできます。

アプリの前提条件

Hilt 依存性注入フレームワークを使用するようにアプリを構成します。

テストで ModuleInstallClient を FakeModuleInstallClient に置き換える

テストで FakeModuleInstallClient を使用するには、ModuleInstallClient バインディングを偽の実装に置き換える必要があります。

1. 依存関係を追加します。

   モジュールの 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'
     }
   

2. ModuleInstallClient を提供する Hilt モジュールを作成します。

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

3. アクティビティに ModuleInstallClient を挿入します。

   Kotlin

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

   Java

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

4. テストのバインディングを置き換えます。

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

   注: このスニペットは、@BindValue を使用して、テストの ModuleInstallClient フィールドを Hilt 依存関係グラフの FakeModuleInstallClient にバインドする基本的な例を示しています。Hilt テストガイドに沿って独自のテスト モジュールを作成し、バインディングを置き換えることもできます。

さまざまなシナリオをシミュレートする

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