ModuleInstallClient ile API kullanılabilirliğini sağlama

Google Play Hizmetleri'ne genel bakış makalesinde açıklandığı gibi, Google Play Hizmetleri tarafından desteklenen SDK'lar, Google onaylı Android cihazlardaki cihaz hizmetleri tarafından desteklenir. Tüm cihaz filosunda depolama alanı ve bellekten tasarruf etmek amacıyla, belirli bir cihazın alakalı işlevler gerektirdiği net olduğunda bazı hizmetler isteğe bağlı olarak yüklenir. Örneğin, Google Play Hizmetleri'nde modelleri kullanırken ML Kiti bu seçeneği sunar.

En yaygın durum, SDK'nın AndroidManifest.xml bağımlılığına bağlı olarak, bir hizmetin (veya "modülün") kendisini gerektiren bir uygulamaya paralel olarak indirilip yüklenmesidir. Daha fazla kontrol için modül yükleme API'leri açık bir şekilde modül kullanılabilirliğini kontrol etme, modül yükleme isteğinde bulunma, istek durumunu izleme ve hataları ele alma olanağı sağlar.

API kullanılabilirliğini ModuleInstallClient ile sağlamak için aşağıdaki adımları uygulayın. Aşağıdaki kod snippet'lerinin örnek kitaplık olarak TensorFlow Lite SDK'sını (play-services-tflite-java) kullandığını, ancak bu adımların OptionalModuleApi ile entegre edilmiş kitaplıklar için geçerli olduğunu unutmayın. Daha fazla SDK destek eklendikçe bu kılavuz ek bilgilerle güncellenecektir.

Başlamadan önce

Uygulamanızı hazırlamak için aşağıdaki bölümlerde yer alan adımları tamamlayın.

Uygulama ön koşulları

Uygulamanızın derleme dosyasında aşağıdaki değerlerin kullanıldığından emin olun:

• minSdkVersion/19 veya daha yüksek

Uygulamanızı yapılandırma

1. En üst düzey settings.gradle dosyanıza Google Maven deposunu ve Maven merkezi deposunu dependencyResolutionManagement bloğuna ekleyin:

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

2. Modülünüzün Gradle derleme dosyasında (genellikle app/build.gradle), play-services-base ve play-services-tflite-java için Google Play Hizmetleri bağımlılarını ekleyin:

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

Modülün kullanılabilirliğini kontrol etme

1. ModuleInstallClient örneğini alın:

   Kotlin

   val moduleInstallClient = ModuleInstall.getClient(context)
   

   Java

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);
   

2. İsteğe bağlı bir modülün kullanılabilirliğini OptionalModuleApi kullanarak kontrol edin:

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

Ertelenen yükleme isteği gönderme

1. ModuleInstallClient örneğini alın:

   Kotlin

   val moduleInstallClient = ModuleInstall.getClient(context)
   

   Java

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);
   

2. Ertelenen isteği gönderin:

   Kotlin

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

   Java

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

Acil modül yükleme isteği gönder

1. ModuleInstallClient örneğini alın:

   Kotlin

   val moduleInstallClient = ModuleInstall.getClient(context)
   

   Java

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);
   

2. (İsteğe bağlı) Yükleme durumu güncellemelerini işlemek için bir InstallStatusListener oluşturun.

   İndirme durumunu özelleştirilmiş bir kullanıcı arayüzünde (örneğin, ilerleme çubuğu) izlemek istiyorsanız yükleme durumu güncellemelerini almak için InstallStatusListener oluşturabilirsiniz.

   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 öğesini yapılandırın ve OptionalModuleApi öğesini isteğe ekleyin:

   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. Yükleme isteğini gönderin:

   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 ile yerel test

Google Play Hizmetleri SDK'ları, bağımlı yerleştirme kullanarak yapılan testlerde modül yükleme API'lerinin sonuçlarını simüle edebilmeniz için FakeModuleInstallClient sağlar.

Uygulama ön koşulları

Uygulamanızı Hit bağımlı bağımlı yerleştirme çerçevesini kullanacak şekilde yapılandırın.

Testteki ModuleInstallClient değerini FakeModuleInstallClient ile değiştirin

1. Bağımlılık ekleyin:

   Modülünüzün Gradle derleme dosyasında (genellikle app/build.gradle), testinize play-services-base-testing için Google Play Hizmetleri bağımlılıklarını ekleyin.

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

2. ModuleInstallClient sağlamak için bir Hilt modülü oluşturun:

   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 etkinliğini etkinliğe ekleyin:

   Kotlin

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

   Java

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

4. Testteki bağlamayı değiştirin:

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

   Not: Yukarıdaki snippet, testinizde ModuleInstallClient alanını Hilt bağımlılık grafiğine kolayca bağlamak için @BindValue kullanmanın temel bir örneğidir.FakeModuleInstallClient Ayrıca, Hit test kılavuzunu uygulayarak kendi test modülünüzü oluşturup bağlantıyı burada değiştirebilirsiniz.

Modül kullanılabilirliğini simüle etme

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

Ertelenen yükleme isteği için sonucu simüle etme

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

Acil yükleme isteği için sonucu simüle et

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