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 sertifikalı Android cihazlardaki cihaz üzerinde hizmetler tarafından desteklenir. Cihaz filosu genelinde depolama alanını ve belleği korumak için belirli bir cihazın ilgili işlevi gerektirdiği anlaşıldığında bazı hizmetler isteğe bağlı olarak yüklenir. Örneğin, Google Play Hizmetleri'nde modeller kullanılırken ML Kit bu seçeneği sunar.

En yaygın durum, SDK'nın AndroidManifest.xml bölümündeki bir bağımlılığa bağlı olarak, bir hizmetin (veya "modülün") gerektirdiği uygulamaya paralel olarak indirilip yüklenmesidir. Modül yükleme API'leri, daha fazla kontrol için modül kullanılabilirliğini açıkça kontrol etme, modül yükleme isteğinde bulunma, istek durumunu izleme ve hataları işleme olanağı sunar.

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

Başlamadan önce

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

Uygulama ön koşulları

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

• 19 veya daha fazla öğede minSdkVersion

Uygulamanızı yapılandırma

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

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

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

   dependencies {
     implementation 'com.google.android.gms:play-services-base:18.5.0'
     implementation 'com.google.android.gms:play-services-tflite-java:16.4.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 OptionalModuleApi değerini kullanarak müsaitlik durumunu 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önderme

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 işleminin ilerleme durumunu özelleştirilmiş bir kullanıcı arayüzünde (ör. ilerleme çubuğu) izlemek istiyorsanız yükleme durumu güncellemelerini almak için bir 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ılık ekleme özelliğini kullanarak testlerde modül yükleme API'lerinin sonuçlarını simüle etmenize olanak tanıyan FakeModuleInstallClient özelliğini sağlar.

Uygulama ön koşulları

Uygulamanızı Hilt bağımlılık ekleme çerçevesini kullanacak şekilde yapılandırın.

Testte ModuleInstallClient yerine FakeModuleInstallClient yazın

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

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

     dependencies {
       // other dependencies...
   
       testImplementation 'com.google.android.gms:play-services-base-testing:16.1.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 öğesini 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, Hilt bağımlılık grafiğinde testinizdeki bir ModuleInstallClient alanını FakeModuleInstallClient alanına kolayca bağlamak için @BindValue kullanmanın temel bir örneğidir. Kendi test modülünüzü oluşturmak ve bağlamayı değiştirmek için Hilt test kılavuzunu da uygulayabilirsiniz.

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 etme

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