إدارة مدى توفّر وحدات "خدمات Google Play" عند الطلب

كما هو موضّح في مقالة نظرة عامة على "خدمات Google Play"، تستند حِزم تطوير البرامج (SDK) التي تستخدم "خدمات Google Play" إلى خدمات على الأجهزة على أجهزة Android المعتمَدة من Google. للحفاظ على مساحة التخزين والذاكرة في جميع الأجهزة، يتم توفير بعض الخدمات كوحدات يتم تثبيتها عند الطلب عندما يحتاج تطبيقك إلى الوظيفة ذات الصلة. على سبيل المثال، توفّر حزمة تعلُّم الآلة هذا الخيار عند استخدام النماذج في "خدمات Google Play".

في معظم الحالات، تنزّل حزمة تطوير البرامج (SDK) الخاصة بخدمات Google Play الوحدات اللازمة وتثبّتها تلقائيًا عندما يستخدم تطبيقك واجهة برمجة تطبيقات تتطلّب هذه الوحدات. ومع ذلك، قد تحتاج إلى المزيد من التحكّم في العملية، مثلاً عندما تريد تحسين تجربة المستخدم من خلال تثبيت الوحدة مسبقًا.

تتيح لك واجهة برمجة التطبيقات ModuleInstallClient تنفيذ ما يلي:

  • تحقَّق مما إذا كانت الوحدات مثبّتة على الجهاز.
  • يجب طلب تثبيت الوحدات.
  • تتبُّع تقدّم عملية التثبيت
  • التعامل مع الأخطاء أثناء عملية التثبيت

يوضّح هذا الدليل كيفية استخدام ModuleInstallClient لإدارة الوحدات في تطبيقك. تجدر الإشارة إلى أنّ مقتطفات الرموز البرمجية التالية تستخدم حزمة تطوير البرامج (SDK) من TensorFlow Lite (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.2'   implementation 'com.google.android.gms:play-services-tflite-java:16.4.0' }

التحقّق من توفّر الوحدات

قبل محاولة تثبيت وحدة، يمكنك التحقّق مما إذا كانت مثبَّتة على الجهاز. يساعدك ذلك في تجنُّب طلبات التثبيت غير الضرورية.

  1. الحصول على مثيل من ModuleInstallClient:

    Kotlin

    val moduleInstallClient = ModuleInstall.getClient(context)

    Java

    ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

  2. تحقَّق من توفّر وحدة باستخدام OptionalModuleApi. يتم توفير واجهة برمجة التطبيقات هذه من خلال حزمة تطوير البرامج (SDK) التي تستخدمها في "خدمات Google Play".

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

طلب تثبيت مؤجّل

إذا لم تكن بحاجة إلى الوحدة على الفور، يمكنك طلب تثبيت مؤجّل. يسمح هذا الإجراء لـ "خدمات Google Play" بتثبيت الوحدة في الخلفية، وربما عندما يكون الجهاز غير نشِط ومتصلاً بشبكة Wi-Fi.

  1. الحصول على مثيل من ModuleInstallClient:

    Kotlin

    val moduleInstallClient = ModuleInstall.getClient(context)

    Java

    ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

  2. أرسِل الطلب المؤجّل:

    Kotlin

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

    Java

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

طلب تثبيت وحدة عاجل

إذا كان تطبيقك يحتاج إلى الوحدة على الفور، يمكنك طلب تثبيت عاجل. سيحاول هذا الخيار تثبيت الوحدة بأسرع ما يمكن، حتى إذا كان ذلك يعني استخدام بيانات الجوّال.

  1. الحصول على مثيل من ModuleInstallClient:

    Kotlin

    val moduleInstallClient = ModuleInstall.getClient(context)

    Java

    ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

  2. (اختياري) أنشئ InstallStatusListener لمراقبة مستوى تقدّم عملية التثبيت.

    إذا كنت تريد عرض مستوى تقدّم عملية التنزيل في واجهة مستخدم تطبيقك (على سبيل المثال، باستخدام شريط تقدّم)، يمكنك إنشاء InstallStatusListener لتلقّي آخر الأخبار.

    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 وأضِف OptionalModuleApi إلى الطلب:

    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. أرسِل طلب التثبيت:

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

اختبار تطبيقك باستخدام FakeModuleInstallClient

توفّر حِزم تطوير البرامج (SDK) الخاصة بـ "خدمات Google Play" FakeModuleInstallClient للسماح لك بمحاكاة نتائج واجهات برمجة التطبيقات الخاصة بتثبيت الوحدات في الاختبارات باستخدام ميزة إدخال التبعية. يساعدك ذلك في اختبار سلوك تطبيقك في سيناريوهات مختلفة بدون الحاجة إلى نشره على جهاز حقيقي.

المتطلبات الأساسية للتطبيق

اضبط تطبيقك لاستخدام إطار عمل 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:

    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 في النشاط:

    Kotlin

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

    Java

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

  4. استبدال عملية الربط في الاختبار:

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

محاكاة سيناريوهات مختلفة

باستخدام FakeModuleInstallClient، يمكنك محاكاة سيناريوهات مختلفة، مثل:

  • الوحدات مثبَّتة من قبل.
  • الوحدات غير متوفّرة على الجهاز.
  • تعذُّر عملية التثبيت
  • نجاح طلب التثبيت المؤجّل أو تعذّره
  • نجاح طلب التثبيت العاجل أو تعذّره

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

محاكاة نتيجة طلب التثبيت المؤجّل

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

محاكاة نتيجة لطلب تثبيت عاجل

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