דף זה תורגם על ידי Cloud Translation API.

הבטחת זמינות של ממשק API באמצעות ModuleInstallClient

כפי שמתואר במאמר סקירה כללית על Google Play Services, ערכות SDK שמבוססות על Google Play Services נתמכות על ידי שירותים במכשיר במכשירי Android שאושרו על ידי Google. כדי לחסוך במקום אחסון ובזיכרון בכל צי המכשירים, חלק מהשירותים מותקנים על פי דרישה כשברור שמכשיר ספציפי זקוק לפונקציונליות הרלוונטית. לדוגמה, ML Kit מספק את האפשרות הזו כשמשתמשים במודלים ב-Google Play Services.

התרחיש הנפוץ ביותר הוא הורדה והתקנה של שירות (או "מודול") במקביל לאפליקציה שדורשת אותו, על סמך תלות ב-AndroidManifest.xml של ה-SDK. כדי לקבל יותר שליטה, ממשקי ה-API להתקנת המודולים מאפשרים לבדוק באופן מפורש את הזמינות של המודולים, לבקש התקנה של מודולים, לעקוב אחרי סטטוס הבקשה ולטפל בשגיאות.

כדי לוודא את הזמינות של ה-API באמצעות ModuleInstallClient, פועלים לפי השלבים הבאים. לתשומת ליבכם: בקטעי הקוד שבהמשך נעשה שימוש ב-TensorFlow Lite SDK (play-services-tflite-java) כספרייה לדוגמה, אבל השלבים האלה רלוונטיים לכל ספרייה שמשולבת עם OptionalModuleApi. נוסיף למדריך הזה מידע נוסף ככל שערכות SDK נוספות יספקו תמיכה.

לפני שמתחילים

כדי להכין את האפליקציה, מבצעים את השלבים שמפורטים בקטעים הבאים.

דרישות מוקדמות להתקנת האפליקציה

מוודאים שבקובץ ה-build של האפליקציה נעשה שימוש בערכים הבאים:

minSdkVersion של 19 או יותר

הגדרת האפליקציה

בקובץ settings.gradle ברמה העליונה, צריך לכלול את מאגר Maven של Google ואת המאגר המרכזי של Maven בתוך הבלוק dependencyResolutionManagement:
```
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}
```
בקובץ ה-build של Gradle של המודול (בדרך כלל app/build.gradle), מוסיפים את התלות של Google Play Services עבור play-services-base ו-play-services-tflite-java:
```
dependencies {
  implementation 'com.google.android.gms:play-services-base:18.5.0'
  implementation 'com.google.android.gms:play-services-tflite-java:16.4.0'
}
```

בדיקת הזמינות של המודולים

אחזור מופע של ModuleInstallClient:

Kotlin

val moduleInstallClient = ModuleInstall.getClient(context)

Java

ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

בודקים את הזמינות של מודול אופציונלי באמצעות OptionalModuleApi שלו:

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

שליחת בקשה להתקנה נדחית

אחזור מופע של ModuleInstallClient:

Kotlin

val moduleInstallClient = ModuleInstall.getClient(context)

Java

ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

שולחים את הבקשה שנדחתה:

Kotlin

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

Java

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

שליחת בקשה דחופה להתקנת מודול

אחזור מופע של ModuleInstallClient:

Kotlin

val moduleInstallClient = ModuleInstall.getClient(context)

Java

ModuleInstallClient moduleInstallClient = ModuleInstall.getClient(context);

(אופציונלי) יוצרים 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();

מגדירים את ModuleInstallRequest ומוסיפים את OptionalModuleApi לבקשה:

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();

שולחים את בקשת ההתקנה:

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`

ערכות ה-SDK של Google Play Services מספקות את FakeModuleInstallClient כדי לאפשר לכם לדמות את התוצאות של ממשקי ה-API להתקנת המודולים בבדיקות באמצעות הזרקת יחסי תלות.

דרישות מוקדמות להתקנת האפליקציה

מגדירים את האפליקציה לשימוש במסגרת ההזרקה של יחסי התלות של Hilt.

מחליפים את `ModuleInstallClient` ב-`FakeModuleInstallClient` בבדיקה

מוסיפים את יחסי התלות:

בקובץ ה-build של Gradle של המודול (בדרך כלל app/build.gradle), מוסיפים את התלות של Google Play Services עבור play-services-base-testing בבדיקה.
```
  dependencies {
    // other dependencies...

    testImplementation 'com.google.android.gms:play-services-base-testing:16.1.0'
  }
```

יצירת מודול 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);
  }
}

מזינים את ModuleInstallClient בפעילות:

Kotlin

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

  ...
}

Java

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

  ...
}

מחליפים את הקישור בבדיקה:

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;

  ...
}

סימולציה של זמינות המודולים

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

הבטחת זמינות של ממשק API באמצעות ModuleInstallClient

לפני שמתחילים

דרישות מוקדמות להתקנת האפליקציה

הגדרת האפליקציה

בדיקת הזמינות של המודולים

Kotlin

Java

Kotlin

Java

שליחת בקשה להתקנה נדחית

Kotlin

Java

Kotlin

Java

שליחת בקשה דחופה להתקנת מודול

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

בדיקה מקומית באמצעות FakeModuleInstallClient

דרישות מוקדמות להתקנת האפליקציה

מחליפים את ModuleInstallClient ב-FakeModuleInstallClient בבדיקה

Kotlin

Java

Kotlin

Java

Kotlin

Java

סימולציה של זמינות המודולים

Kotlin

Java

סימולציה של תוצאה לבקשת התקנה שהושהתה

Kotlin

Java

הדמיה של תוצאה לבקשת התקנה דחופה

Kotlin

Java

בדיקה מקומית באמצעות `FakeModuleInstallClient`

מחליפים את `ModuleInstallClient` ב-`FakeModuleInstallClient` בבדיקה