Как управлять доступностью модулей сервисов Google Play по запросу

Как описано в статье Общие сведения о сервисах Google Play, SDK, работающие на основе сервисов Google Play, поддерживаются локальными сервисами на сертифицированных Google устройствах Android. Чтобы экономить память на устройствах, некоторые сервисы предоставляются в виде модулей, которые устанавливаются по запросу, когда приложению требуется соответствующая функция. Например, ML Kit предоставляет такую возможность при использовании моделей в сервисах Google Play.

В большинстве случаев SDK сервисов Google Play автоматически скачивает и устанавливает необходимые модули, когда ваше приложение использует API, для которого они требуются. Однако вы можете захотеть лучше контролировать этот процесс, например, если вы хотите улучшить пользовательский опыт, установив модуль заранее.

ModuleInstallClient API позволяет:

• Проверьте, установлены ли модули на устройстве.
• Запросите установку модулей.
• Отслеживайте ход установки.
• Устраните ошибки, возникшие в процессе установки.

В этом руководстве рассказывается, как управлять модулями в приложении с помощью ModuleInstallClient. Обратите внимание, что в приведенных ниже фрагментах кода в качестве примера используется TensorFlow Lite SDK (play-services-tflite-java), но эти шаги применимы к любой библиотеке, интегрированной с OptionalModuleApi.

Подготовка

Чтобы подготовить приложение, выполните нужные действия в разделах, указанных ниже.

Требования к приложению

Убедитесь, что в файле сборки приложения приведены значения, указанные ниже.

• minSdkVersion: 23 и выше

Настройка приложения

1. Добавьте репозиторий Google Maven и центральный репозиторий Maven в блок dependencyResolutionManagement файла settings.gradle верхнего уровня:

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

2. В файле build.gradle модуля (обычно это app/build.gradle) добавьте зависимости сервисов Google Play для play-services-base и play-services-tflite-java:

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

Проверьте, доступны ли модули

Прежде чем устанавливать модуль, проверьте, не установлен ли он уже на устройстве. Это поможет избежать ненужных запросов на установку.

1. Получите экземпляр ModuleInstallClient:

   Kotlin

   val moduleInstallClient = ModuleInstall.getClient(context)

   Java

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

2. Проверьте доступность модуля с помощью его OptionalModuleApi. Этот API предоставляется SDK сервисов Google Play, который вы используете.

   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, чтобы отслеживать ход установки.

   Если вы хотите показывать ход скачивания в интерфейсе приложения (например, с помощью индикатора выполнения), создайте 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

В SDK сервисов Google Play есть FakeModuleInstallClient, который позволяет имитировать результаты API установки модулей в тестах с помощью внедрения зависимостей. Это позволяет тестировать поведение приложения в разных сценариях без необходимости развертывать его на реальном устройстве.

Требования к приложению

Настройте приложение так, чтобы оно использовало фреймворк внедрения зависимостей Hilt.

Заменить ModuleInstallClient на FakeModuleInstallClient в тесте

Чтобы использовать FakeModuleInstallClient в тестах, нужно заменить привязку ModuleInstallClient на фиктивную реализацию.

1. Добавьте зависимость:

   В файле build.gradle модуля (обычно app/build.gradle) добавьте зависимости сервисов Google Play для play-services-base-testing в тесте.

     dependencies {
       // other dependencies...
   
       testImplementation 'com.google.android.gms:play-services-base-testing:16.2.0'
     }
   

2. Создайте модуль 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);
     }
   }

3. Внедрите ModuleInstallClient в объект activity:

   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 к FakeModuleInstallClient в тесте в графе зависимостей Hilt. Вы также можете создать собственный тестовый модуль и заменить в нем привязку, следуя руководству по тестированию 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...
}