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

كما هو موضّح في مقالة نظرة عامة على "خدمات Google Play"، تستند حِزم تطوير البرامج (SDK) المتوافقة مع "خدمات Google Play" إلى خدمات على الجهاز على أجهزة Android المعتمَدة من Google. للحفاظ على مساحة التخزين والذاكرة في مجموعة الأجهزة بأكملها، يتم توفير بعض الخدمات كوحدات يتم تثبيتها عند الطلب عندما يتطلب تطبيقك الوظيفة ذات الصلة. على سبيل المثال، توفّر حزمة ML Kit هذا الخيار عند استخدام النماذج في "خدمات 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 build لوحدتك (عادةً app/build.gradle)، أضِف متطلّبات "خدمات Google Play" لإصدارَي play-services-base و play-services-tflite-java:

    dependencies {
  implementation 'com.google.android.gms:play-services-base:18.7.0'
  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 للسماح لك بمحاولة محاكاة نتائج واجهات برمجة التطبيقات الخاصة بتثبيت الوحدة في الاختبارات باستخدام ميزة FakeModuleInstallClient. يساعدك ذلك في اختبار سلوك تطبيقك في سيناريوهات مختلفة بدون الحاجة إلى نشره على جهاز حقيقي.

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

اضبط تطبيقك لاستخدام إطار عمل Hilt لإدخال التبعية.

استبدال ModuleInstallClient بـ FakeModuleInstallClient في الاختبار

لاستخدام FakeModuleInstallClient في اختباراتك، عليك استبدال ربط ModuleInstallClient بالتطبيق المزيّف.

  1. إضافة تبعية:

    في ملف Gradle build لوحدتك (عادةً 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...
}