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

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

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

API ModuleInstallClient дает вам возможность:

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

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

Прежде чем начать

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

Предварительные условия приложения

Убедитесь, что файл сборки вашего приложения использует следующие значения:

• minSdkVersion 23 или выше

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

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

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

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

   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 :

   Котлин

   val moduleInstallClient = ModuleInstall.getClient(context)

   Ява

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

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

   Котлин

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

   Ява

   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 :

   Котлин

   val moduleInstallClient = ModuleInstall.getClient(context)

   Ява

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

2. Отправить отложенный запрос:

   Котлин

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

   Ява

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

Запросить срочную установку модуля

Если вашему приложению модуль нужен немедленно, вы можете запросить срочную установку. Это попытается установить модуль как можно быстрее, даже если это означает использование мобильных данных.

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

   Котлин

   val moduleInstallClient = ModuleInstall.getClient(context)

   Ява

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

2. (Необязательно) Создайте InstallStatusListener для отслеживания хода установки.

   Если вы хотите отображать ход загрузки в пользовательском интерфейсе вашего приложения (например, с помощью индикатора выполнения), вы можете создать InstallStatusListener для получения обновлений.

   Котлин

   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()

   Ява

   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 к запросу:

   Котлин

   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()

   Ява

   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. Отправьте запрос на установку:

   Котлин

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

   Ява

   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. Добавить зависимость:

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

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

2. Создайте модуль Hilt для предоставления ModuleInstallClient :

   Котлин

   @Module
   @InstallIn(ActivityComponent::class)
   object ModuleInstallModule {
   
     @Provides
     fun provideModuleInstallClient(
       @ActivityContext context: Context
     ): ModuleInstallClient = ModuleInstall.getClient(context)
   }

   Ява

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

3. Внедрите ModuleInstallClient в действие:

   Котлин

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

   Ява

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

4. Заменить привязку в тесте:

   Котлин

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

   Ява

   @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 вы можете моделировать различные сценарии, такие как:

• Модули уже установлены.
• Модули недоступны на устройстве.
• Процесс установки завершается неудачей.
• Запрос на отложенную установку выполнен успешно или неудачно.
• Запрос на срочную установку выполнен успешно или неудачно.

Котлин

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

Ява

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

Имитация результата для запроса отложенной установки

Котлин

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

Ява

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

Имитация результата для срочного запроса на установку

Котлин

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

Ява

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