שליחת הודעה לבודקים על גרסאות 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, לוחצים על Enable.

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

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

• 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: מגדירים התראות בתוך האפליקציה

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

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

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

הגדרה בסיסית

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

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

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

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

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

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

אפשר להפעיל את 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 יותר מפעם אחת