API-Verfügbarkeit mit ModuleInstallClient sicherstellen

Wie im Artikel Übersicht über die Google Play-Dienste beschrieben, werden SDKs, die durch Google Play-Dienste bereitgestellt werden, von Diensten auf dem Gerät auf Google-zertifizierten Android-Geräten unterstützt. Um Speicher und Arbeitsspeicher auf dem gesamten Gerätepool zu sparen, werden einige Dienste on demand installiert, wenn klar ist, dass ein bestimmtes Gerät die entsprechenden Funktionen benötigt. Beispielsweise bietet ML Kit diese Option, wenn Sie Modelle in Google Play-Diensten verwenden.

In den meisten Fällen wird ein Dienst (oder „Modul“) parallel zu einer Anwendung heruntergeladen und installiert, die ihn benötigt, basierend auf einer Abhängigkeit in der AndroidManifest.xml des SDK. Für mehr Kontrolle bieten die APIs zur Modulinstallation die Möglichkeit, explizit die Modulverfügbarkeit zu prüfen, die Modulinstallation anzufordern, den Anfragestatus zu überwachen und Fehler zu beheben.

Führen Sie die folgenden Schritte aus, um die API-Verfügbarkeit mit ModuleInstallClient sicherzustellen. In den Code-Snippets unten wird das TensorFlow Lite SDK (play-services-tflite-java) als Beispielbibliothek verwendet. Diese Schritte gelten jedoch für jede Bibliothek, die in OptionalModuleApi integriert ist. Dieser Leitfaden wird mit zusätzlichen Informationen aktualisiert, sobald weitere SDKs Unterstützung hinzufügen.

Hinweis

Führen Sie die Schritte in den folgenden Abschnitten aus, um Ihre App vorzubereiten.

Voraussetzungen für Apps

Achten Sie darauf, dass die Build-Datei Ihrer App die folgenden Werte verwendet:

• minSdkVersion von 19 oder höher

Eigene App konfigurieren

1. Fügen Sie in der Datei settings.gradle auf oberster Ebene das Maven-Repository von Google und das Maven Central Repository innerhalb des dependencyResolutionManagement-Blocks ein:

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

2. Füge in der Gradle-Build-Datei des Moduls (in der Regel app/build.gradle) die Abhängigkeiten der Google Play-Dienste für play-services-base und play-services-tflite-java hinzu:

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

Modulverfügbarkeit prüfen

1. Rufen Sie eine Instanz von ModuleInstallClient ab:

   Kotlin

   val moduleInstallClient = ModuleInstall.getClient(context)
   

   Java

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);
   

2. Prüfe die Verfügbarkeit eines optionalen Moduls mithilfe des zugehörigen 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…
           });
   

Anfrage für verzögerte Installation senden

1. Rufen Sie eine Instanz von ModuleInstallClient ab:

   Kotlin

   val moduleInstallClient = ModuleInstall.getClient(context)
   

   Java

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);
   

2. Senden Sie die verzögerte Anfrage:

   Kotlin

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

   Java

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

Dringende Anfrage zur Modulinstallation senden

1. Rufen Sie eine Instanz von ModuleInstallClient ab:

   Kotlin

   val moduleInstallClient = ModuleInstall.getClient(context)
   

   Java

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);
   

2. (Optional) Erstellen Sie eine InstallStatusListener, um Updates des Installationsstatus zu verarbeiten.

   Wenn Sie den Downloadfortschritt in einer benutzerdefinierten UI (z. B. einer Fortschrittsanzeige) beobachten möchten, können Sie einen InstallStatusListener erstellen, um Updates zum Installationsstatus zu erhalten.

   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. Konfigurieren Sie ModuleInstallRequest und fügen Sie der Anfrage das OptionalModuleApi hinzu:

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

4. Installationsanforderung senden:

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

Lokale Tests mit FakeModuleInstallClient

Google Play-Dienste-SDKs bieten die FakeModuleInstallClient, damit du die Ergebnisse der Modulinstallations-APIs in Tests mit Abhängigkeitsinjektion simulieren kannst.

Voraussetzungen für Apps

Konfigurieren Sie Ihre App für die Verwendung des Hilt-Abhängigkeitsinjektions-Frameworks.

ModuleInstallClient im Test durch FakeModuleInstallClient ersetzen

1. Abhängigkeit hinzufügen:

   Füge in deinem Test in der Gradle-Build-Datei des Moduls (in der Regel app/build.gradle) die Abhängigkeiten der Google Play-Dienste für play-services-base-testing hinzu.

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

2. Erstellen Sie ein Hilt-Modul, um ModuleInstallClient bereitzustellen:

   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. Fügen Sie ModuleInstallClient in die Aktivität ein:

   Kotlin

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

   Java

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

4. Ersetzen Sie die Bindung im Test:

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

   Hinweis: Das obige Snippet ist ein einfaches Beispiel für die Verwendung von @BindValue, um ein ModuleInstallClient-Feld in Ihrem Test einfach an FakeModuleInstallClient zu binden. Sie können auch dem Hilt-Testleitfaden folgen, um Ihr eigenes Testmodul zu erstellen und die Bindung dort zu ersetzen.

Modulverfügbarkeit simulieren

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

Ergebnis für eine verzögerte Installationsanfrage simulieren

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

Ergebnis für eine dringende Installationsanfrage simulieren

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