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

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

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

אם עדיין לא הוספתם את Firebase לפרויקט Android, אתם צריכים להוסיף אותו.

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

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

2. בקטע Firebase App Testers API (ממשק API לבדיקת אפליקציות ב-Firebase), לוחצים על הפעלה.

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

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

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

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

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

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

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

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

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

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

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

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

הגדרה בסיסית

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

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

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

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

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

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

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

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

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

// 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 כדי לבדוק אם יש לו גישה לגרסה חדשה.

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

// 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():

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

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

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

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

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

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

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

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

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

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

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

שלב 4: בנייה ובדיקה של ההטמעה

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

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

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