שליחת הודעה לבודקים על גרסאות build חדשות


ערכות ה-SDK האופציונליות של Firebase App Distribution ל-iOS ול-Android מאפשרות לכם להציג התראות באפליקציה לבודקים כשגרסאות build חדשות של האפליקציה זמינות להתקנה. במדריך הזה מוסבר איך להשתמש ב-SDK של App Distribution ל-iOS ול-Android כדי ליצור התראות על גרסאות build חדשות ולהתאים אותן אישית למטרות בדיקה.

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

אם עדיין לא עשיתם זאת, מוסיפים את Firebase לפרויקט Android.

שלב 1: מפעילים את App Distribution Tester API

  1. בוחרים את הפרויקט במסוף Google Cloud.

  2. בקטע Firebase App Testers API לוחצים על הפעלה.

שלב 2: מוסיפים את App Distribution לאפליקציה

App Distribution SDK של Android מורכב משתי ספריות:

  • firebase-appdistribution-api – הספרייה של ה-API בלבד, שאפשר לכלול בכל גרסאות ה-build.
  • firebase-appdistribution – הטמעה מלאה של ה-SDK (אופציונלי).

הספרייה שמבוססת על API בלבד מאפשרת לקוד לבצע קריאות ל-SDK. לשיחות לא תהיה השפעה אם ההטמעה המלאה של ה-SDK לא תהיה.

מגדירים את התלות ב-Android SDK של App Distribution בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל מדובר בקובץ <project>/<app-module>/build.gradle.kts או <project>/<app-module>/build.gradle). כדי לא לכלול את הפונקציונליות של העדכון העצמאי של הטמעת ה-SDK המלאה בגרסאות ה-build של Play, מוסיפים את התלות בספרייה של ה-API בלבד לכל גרסאות ה-build. מוסיפים את ההטמעה המלאה של ה-SDK רק לגרסאות שמתכוונות אך ורק לבדיקת טרום-השקה.

dependencies {
    // ADD the API-only library to all variants
    implementation("com.google.firebase:firebase-appdistribution-api:16.0.0-beta14")

    // ADD the full SDK implementation to the "beta" variant only (example)
    betaImplementation("com.google.firebase:firebase-appdistribution:16.0.0-beta14")
}

מחפשים מודול ספרייה ספציפי ל-Kotlin? החל מהגרסה של אוקטובר 2023, מפתחי Kotlin ו-Java יכולים להסתמך על מודול הספרייה הראשי (פרטים נוספים זמינים בשאלות הנפוצות על היוזמה הזו).

שלב 3: מגדירים התראות בתוך האפליקציה

ב-Android SDK App Distribution יש את הדרכים הבאות להגדיר התראות לגבי גרסאות build מתוך האפליקציה לבודקים:

  • הגדרה בסיסית של התראה שמגיעה יחד עם תיבות דו-שיח עם עדכון לאפליקציה מוכנות מראש ותיבות דו-שיח להצגה לבודקים.
  • הגדרה מתקדמת של התראות שמאפשרת להתאים אישית את ממשק המשתמש.

אם זו הפעם הראשונה שאתם משתמשים ב-Android SDK App Distribution, מומלץ להשתמש בהגדרה בסיסית.

הגדרה בסיסית

משתמשים ב-updateIfNewReleaseAvailable כדי להציג תיבת דו-שיח מוגדרת מראש להפעלת התראות למשתמשי הבדיקה שעדיין לא הפעילו את ההתראות, ולאחר מכן בודקים אם יש גרסה חדשה של build. כשמפעילים את ה-method, הוא מבצע את התהליך הבא:

  1. הפונקציה בודקת אם הבודק הפעיל התראות. אם הבודקים עדיין לא הפעילו התראות, השיטה תנחה אותו להיכנס ל-App Distribution באמצעות חשבון Google שלו.

  2. חיפוש גרסאות build חדשות זמינות להתקנה על ידי הבודקים.

  3. הצגת התראה מוגדרת מראש עם הבודק לבצע עדכון.

  4. אם ה-build החדש הוא קובץ Android App Bundle (AAB), הוא מפנה את הבדיקה אל Google Play כדי להשלים את תהליך העדכון.

    אם ה-build החדש הוא אפליקציית PacKage (APK) ל-Android, ה-SDK מוריד את ה-build החדש ברקע ומבקש מהבודק להתקין אותו. ה-SDK שולח התראות על התקדמות ההורדה למשתמש באמצעות NotificationManager. תוכלו גם להוסיף אינדיקטור התקדמות משלכם על ידי צירוף handler של onProgressUpdate למשימה updateIfNewReleaseAvailable.

אפשר להפעיל את updateIfNewReleaseAvailable בכל שלב באפליקציה. לדוגמה, אפשר להפעיל את updateIfNewReleaseAvailable במהלך השיטה onResume של הפעילות הראשית של האפליקציה.

בדוגמה הבאה בודקים אם הבודק הפעיל התראות ויש לו גישה ל-build חדש. אם התנאים האלה מתקיימים, תוצג תיבת דו-שיח כשהגרסה הזמינה להתקנה:

Kotlin+KTX

// Copy and paste this into any part of your app - for example, in your main
// activity's onResume method.
val firebaseAppDistribution = FirebaseAppDistribution.getInstance()
firebaseAppDistribution.updateIfNewReleaseAvailable()
    .addOnProgressListener { updateProgress ->
      // (Optional) Implement custom progress updates in addition to
      // automatic NotificationManager updates.
    }
    .addOnFailureListener { e ->
      // (Optional) Handle errors.
      if (e is FirebaseAppDistributionException) {
        when (e.errorCode) {
          Status.NOT_IMPLEMENTED -> {
            // SDK did nothing. This is expected when building for Play.
          }
          else -> {
            // Handle other errors.
          }
        }
      }
    }

Java

// Copy and paste this into any part of your app - for example, in your main
// activity's onResume method.
FirebaseAppDistribution firebaseAppDistribution = FirebaseAppDistribution.getInstance();
firebaseAppDistribution.updateIfNewReleaseAvailable()
    .addOnProgressListener(updateProgress -> {
      // (Optional) Implement custom progress updates in addition to
      // automatic NotificationManager updates.
    })
    .addOnFailureListener(e -> {
      // (Optional) Handle errors.
      if (e instanceof FirebaseAppDistributionException) {
        switch (((FirebaseAppDistributionException)e).getErrorCode()) {
          case NOT_IMPLEMENTED:
            // SDK did nothing. This is expected when building for Play.
            break;
          default:
            // Handle other errors.
            break;
        }
      }
    });

תצורה מתקדמת

הגדרות כניסה מתקדמות

השיטות signInTester ו-isTesterSignedIn מעניקות לכם גמישות רבה יותר להתאמה אישית של חוויית הכניסה של הבודקים, כך שחוויית הבדיקה תתאים יותר למראה ולתחושה של האפליקציה.

בדוגמה הבאה בודקים אם הבודק כבר נכנס לחשבון הבדיקה App Distribution. כך תוכלו להציג את ממשק המשתמש (UI) שלכם לכניסה רק לבודקים שעדיין לא נכנסו לחשבון. אחרי שהבודק ייכנס לחשבון, אפשר יהיה להפעיל את updateIfNewReleaseAvailable כדי לבדוק אם לבודק יש גישה לגרסת build חדשה.

Kotlin+KTX

// Only show sign-in UI if this is the "beta" variant (example).
if (BuildConfig.BUILD_TYPE == "beta" && !firebaseAppDistribution.isTesterSignedIn) {
    // Start your sign-in UI here.
}

// Only check for updates if the tester is already signed in (do not prompt).
if (firebaseAppDistribution.isTesterSignedIn) {
    firebaseAppDistribution.updateIfNewReleaseAvailable().addOnFailureListener {
        // Handle failed update.
    }
}

Java

// Only show sign-in UI if this is the "beta" variant (example).
if (BuildConfig.BUILD_TYPE == "beta" && !firebaseAppDistribution.isTesterSignedIn()) {
    // Start your sign-in UI here.
}

// Only check for updates if the tester is already signed in (do not prompt).
if (firebaseAppDistribution.isTesterSignedIn()) {
    firebaseAppDistribution.updateIfNewReleaseAvailable().addOnFailureListener( e -> {
        // Handle failed update.
    });
}

מממשק המשתמש לכניסה, כשהבודק בוחר להמשיך, מבצעים קריאה אל signInTester():

Kotlin+KTX

firebaseAppDistribution.signInTester().addOnSuccessListener {
  // Handle successful sign-in.
}.addOnFailureListener {
  // Handle failed sign-in.
});

Java

firebaseAppDistribution.signInTester().addOnSuccessListener( unused -> {
  // Handle successful sign-in.
}).addOnFailureListener(e -> {
  // Handle failed sign-in.
});

הגדרות של עדכון מתקדם

השיטות checkForNewRelease ו-updateApp מספקות יותר גמישות להתאמה אישית של המועד שבו הבודקים מתבקשים לעדכן. אתם יכולים גם להתאים אישית את תיבת הדו-שיח של העדכון המובנית ואת אינדיקטור התקדמות ההורדה כך שיתאימו יותר למראה ולתחושה של האפליקציה.

לתשומת ליבכם: updateApp לא מציגה אינדיקציה לגבי התקדמות ההורדה. כלומר, תצטרכו להטמיע אינדיקציה משלכם להתקדמות באמצעות NotificationManager, תצוגת סטטוס כלשהי באפליקציה או גישה אחרת.

בדוגמה הבאה בודקים אם יש גרסה חדשה זמינה, ואז מציגים ממשק משתמש בהתאמה אישית. לפני שמפעילים את checkForNewRelease ו-updateApp, צריך לוודא שהבודק נכנס לחשבון באמצעות הגדרת כניסה מתקדמת.

Kotlin+KTX

firebaseAppDistribution.checkForNewRelease().addOnSuccessListener { release ->
    if (release != null) {
        // New release available. Start your update UI here.
    }
}.addOnFailureListener {
    // Handle failed check for new release. Fails with Status#NOT_IMPLEMENTED
    // if built for Play.
}

Java

firebaseAppDistribution.checkForNewRelease().addOnSuccessListener(release -> {
    if (release != null) {
        // New release available. Start your update UI here.
    }
}).addOnFailureListener(e -> {
    // Handle failed check for new release. Fails with Status#NOT_IMPLEMENTED
    // if built for Play.
});

כשהבוחרים ממשיכים בעדכון בממשק המשתמש של העדכון, צריך לבצע את ההפעלה הבאה:

Kotlin+KTX

firebaseAppDistribution.updateApp()
    .addOnProgressListener { updateState ->
      // Use updateState to show update progress.
    }

Java

firebaseAppDistribution.updateApp()
    .addOnProgressListener(updateState -> {
      // Use updateState to show update progress.
    });

שלב 4: יוצרים ובודקים את ההטמעה

כדי לפתח את האפליקציה ולבדוק את ההטמעה, מפיצים את הגרסה היציבה לבודקים באמצעות מסוף Firebase.

תוכלו להיעזר במדריך לפתרון בעיות של App Distribution לקבלת עזרה עם בעיות נפוצות, כמו:

  • הבודק לא מקבל התראות מתוך האפליקציה
  • הבודק מתבקש להיכנס ל-Google יותר מפעם אחת