İsteğe bağlı Google Play Hizmetleri modüllerinin kullanılabilirliğini yönetme

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. Tüm cihaz filosunda depolama alanı ve bellek tasarrufu sağlamak için bazı hizmetler, uygulamanız ilgili işlevi gerektirdiğinde isteğe bağlı olarak yüklenen modüller olarak sağlanır. Örneğin, Google Play hizmetlerinde modeller kullanılırken ML Kit bu seçeneği sunar.

Çoğu durumda Google Play Hizmetleri SDK'sı, uygulamanız bunları gerektiren bir API kullandığında gerekli modülleri otomatik olarak indirip yükler. Ancak modülü önceden yükleyerek kullanıcı deneyimini iyileştirmek istediğinizde olduğu gibi, süreç üzerinde daha fazla kontrole sahip olmak isteyebilirsiniz.

ModuleInstallClient API'si sayesinde şunları yapabilirsiniz:

• Modüllerin cihaza önceden yüklenmiş olup olmadığını kontrol edin.
• Modülleri yükleme isteğinde bulunun.
• Yükleme işleminin ilerleme durumunu izleyin.
• Yükleme işlemi sırasındaki hataları işleme

Bu kılavuzda, uygulamanızdaki modülleri yönetmek için ModuleInstallClient'ü nasıl kullanacağınız gösterilmektedir. Aşağıdaki kod snippet'lerinde örnek olarak TensorFlow Lite SDK (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.

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:

• 23 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.7.0'
     implementation 'com.google.android.gms:play-services-tflite-java:16.4.0'
   }
   

Modüllerin kullanılabilir olup olmadığını kontrol etme

Bir modülü yüklemeye çalışmadan önce, cihazda yüklü olup olmadığını kontrol edebilirsiniz. Bu sayede gereksiz yükleme isteklerinden kaçınabilirsiniz.

1. ModuleInstallClient örneğini alın:

   Kotlin

   val moduleInstallClient = ModuleInstall.getClient(context)

   Java

   ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

2. OptionalModuleApi özelliğini kullanarak bir modülün kullanılabilirliğini kontrol edin. Bu API, kullandığınız Google Play Hizmetleri SDK'sı tarafından sağlanır.

   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ğinde bulunma

Modüle hemen ihtiyacınız yoksa ertelenen yükleme isteğinde bulunabilirsiniz. Bu sayede Google Play Hizmetleri, modülü arka planda (cihaz boşta ve kablosuz ağa bağlıyken) yükleyebilir.

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ğinde bulunma

Uygulamanızın modüle hemen ihtiyacı varsa acil yükleme isteğinde bulunabilirsiniz. Bu işlem, mobil veri kullanılacak olsa bile modülü mümkün olduğunca hızlı bir şekilde yüklemeye çalışır.

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 ilerleme durumunu izlemek için bir InstallStatusListener oluşturun.

   İndirme ilerleme durumunu uygulamanızın kullanıcı arayüzünde görüntülemek istiyorsanız (örneğin, bir ilerleme çubuğuyla) güncelleme 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 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. Yükleme isteğini gönderin:

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

Uygulamanızı FakeModuleInstallClient ile test etme

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. Bu sayede, uygulamanızı gerçek bir cihaza dağıtmanıza gerek kalmadan farklı senaryolarda davranışını test edebilirsiniz.

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

Testlerinizde FakeModuleInstallClient kullanmak için ModuleInstallClient bağlamasını sahte uygulamayla değiştirmeniz gerekir.

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: Bu snippet'te, testinizdeki bir ModuleInstallClient alanını Hilt bağımlılık grafiğindeki FakeModuleInstallClient alanına bağlamak için @BindValue kullanımıyla ilgili temel bir örnek gösterilmektedir. Kendi test modülünüzü oluşturmak ve bağlamayı değiştirmek için Hilt test kılavuzunu da uygulayabilirsiniz.

Farklı senaryoları simüle etme

FakeModuleInstallClient ile aşağıdaki gibi farklı senaryoları simüle edebilirsiniz:

• Modüller zaten yüklü.
• Cihazda modüller kullanılamıyor.
• Yükleme işlemi başarısız olur.
• Ertelenen yükleme isteği başarılı olur veya başarısız olur.
• Acil yükleme isteği başarılı olur veya başarısız olur.

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