הפצת אפליקציות ל-Android לבודקים באמצעות Gradle


אפשר לשלב את App Distribution בתהליך ה-build של Android באמצעות הפלאגין App Distribution ל-Gradle. הפלאגין מאפשר לציין את הבדיקות ואת הערות המוצר בקובץ Gradle של האפליקציה, וכך להגדיר הפצות לסוגים שונים של גרסאות build ולוריאציות שונות של האפליקציה.

במדריך הזה מוסבר איך להפיץ חבילות Android App Bundle (AAB) למפתחים לצורך בדיקה באמצעות הפלאגין App Distribution של Gradle.

App Distribution משתלב עם שירות השיתוף הפנימי של האפליקציות של Google Play כדי לעבד את קובצי ה-AAB שאתם מעלים ולהציג חבילות APK שעברו אופטימיזציה לתצורות המכשירים של הבוחנים. הפצת אפליקציות AAB מאפשרת לכם:

  • להריץ חבילות APK שעברו אופטימיזציה (ש-Google Play מספקת) ומותאמות למכשירים של הבוחנים.

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

  • לבדוק את התכונות של חבילות האפליקציות, כמו הפצת פיצ'רים ב-Play ו-Play Asset Delivery.

  • להקטין את גודל ההורדות של הבודקים.

ההרשאות הנדרשות

כדי להעלות קובצי AAB אל App Distribution, צריך לקשר את אפליקציית Firebase לאפליקציה ב-Google Play. כדי לבצע את הפעולות האלה, צריכה להיות לכם רמת הגישה הנדרשת.

אם אין לכם את הרשאת הגישה הנדרשת ל-Firebase, אתם יכולים לבקש מהבעלים של הפרויקט ב-Firebase להקצות לכם את התפקיד המתאים דרך הגדרות IAM במסוף Firebase. אם יש לכם שאלות לגבי הגישה לפרויקט ב-Firebase, כולל איך למצוא בעלים או להקצות בעלים, תוכלו לעיין בשאלות הנפוצות בנושא 'הרשאות וגישה לפרויקטים ב-Firebase'.

הטבלה הבאה רלוונטית לקישור אפליקציה ב-Firebase לאפליקציה ב-Google Play, וגם להעלאת חבילות AAB.

פעולה במסוף Firebase הרשאת IAM נדרשת תפקידי IAM שכוללים את ההרשאות הנדרשות כברירת מחדל תפקידים נדרשים נוספים
קישור אפליקציה ב-Firebase לאפליקציה ב-Google Play firebase.playLinks.update אחד מהתפקידים הבאים: גישה לחשבון פיתוח ב-Google Play בתור אדמין
העלאת קובצי AAB אל App Distribution firebaseappdistro.releases.update אחד מהתפקידים הבאים: ––

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

  1. אם עדיין לא עשיתם זאת, מוסיפים את Firebase לפרויקט Android. בסוף תהליך העבודה הזה תהיה לכם אפליקציית Android ב-Firebase בפרויקט שלכם ב-Firebase.

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

  2. כדי ליצור קישור של Firebase ל-Google Play ולהעלות קובצי AAB, עליכם לוודא שהאפליקציה שלכם עומדת בדרישות הבאות:

    • האפליקציה ב-Google Play ואפליקציית Firebase ל-Android רשומות עם אותו שם חבילה.

    • האפליקציה ב-Google Play מוגדרת במרכז הבקרה של האפליקציות ומופצת באחד מהמסלולים של Google Play (בדיקה פנימית, בדיקה בקבוצה מוגדרת, בדיקה של הקהל הרחב או ייצור).

    • הבדיקה של האפליקציה ב-Google Play הושלמה והאפליקציה פורסמה. האפליקציה שלכם תפורסם אם בעמודה סטטוס האפליקציה יופיע אחד מהסטטוסים הבאים: בדיקה פנימית (לא בדיקה פנימית של גרסת טיוטה), בדיקה בקבוצה מוגדרת, בדיקה של הקהל הרחב או סביבת ייצור.

  3. מקשרים את אפליקציית Android ב-Firebase לחשבון הפיתוח ב-Google Play:

    1. במסוף Firebase, עוברים אל Project settings ובוחרים בכרטיסייה Integrations.

    2. בכרטיס Google Play, לוחצים על Link (קישור).
      אם כבר יש לכם קישורים ל-Google Play, לוחצים במקום זאת על Manage (ניהול).

    3. פועלים לפי ההוראות במסך כדי להפעיל את השילוב עם App Distribution ולבחור לאילו אפליקציות ל-Android של Firebase לקשר את Google Play.

    מידע נוסף על קישור ל-Google Play

שלב 1. הגדרת הפרויקט ל-Android

  1. בקובץ Gradle ברמה הבסיסית (ברמת הפרויקט) (<project>/build.gradle.kts או <project>/build.gradle), מוסיפים את הפלאגין App Distribution של Gradle כיחס תלות:

    KotlinGroovy
    plugins {
    // ...
    id("com.android.application") version "7.3.0" apply false

    // Make sure that you have the Google services Gradle plugin dependency
    id("com.google.gms.google-services") version "4.4.2" apply false

    // Add the dependency for the App Distribution Gradle plugin
    id("com.google.firebase.appdistribution") version "5.1.1" apply false
}
    plugins {
    // ...
    id 'com.android.application' version '7.3.0' apply false

    // Make sure that you have the Google services Gradle plugin dependency
    id 'com.google.gms.google-services' version '4.4.2' apply false

    // Add the dependency for the App Distribution Gradle plugin
    id 'com.google.firebase.appdistribution' version '5.1.1' apply false
}

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

    KotlinGroovy
    plugins {
  id("com.android.application")

  // Make sure that you have the Google services Gradle plugin
  id("com.google.gms.google-services")

  // Add the App Distribution Gradle plugin
  id("com.google.firebase.appdistribution")
}
    plugins {
  id 'com.android.application'

  // Make sure that you have the Google services Gradle plugin
  id 'com.google.gms.google-services'

  // Add the App Distribution Gradle plugin
  id 'com.google.firebase.appdistribution'
}

  3. אם אתם מאחורי שרת proxy או חומת אש של ארגון, צריך להוסיף את מאפיין המערכת של Java הבא כדי לאפשר ל-App Distribution להעלות את ההפצות שלכם ל-Firebase:

    -Djavax.net.ssl.trustStore=/path/to/truststore -Djavax.net.ssl.trustStorePassword=password

שלב 2. אימות באמצעות Firebase

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

אימות באמצעות חשבון שירות מאפשר לכם להשתמש בפלאשין בצורה גמישה עם מערכת האינטגרציה הרצייפה (CI) שלכם. יש שתי דרכים לספק את פרטי הכניסה של חשבון השירות:

  • מעבירים את קובץ המפתח של חשבון השירות אל build.gradle. השיטה הזו נוחה אם כבר יש לכם את קובץ המפתח של חשבון השירות בסביבת ה-build.
  • מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS כך שיצביע על קובץ המפתח של חשבון השירות. כדאי להשתמש בשיטה הזו אם כבר הגדרתם את Application Default Credentials ‏ (ADC) לשירות אחר של Google (למשל, Google Cloud).

כדי לבצע אימות באמצעות פרטי הכניסה של חשבון השירות:

  1. במסוף Google Cloud,בוחרים את הפרויקט ויוצרים חשבון שירות חדש.
  2. מוסיפים את התפקיד Firebase App Distribution אדמין.
  3. יוצרים מפתח JSON פרטי ומעבירים את המפתח למיקום שגלוי לסביבת ה-build. חשוב לשמור את הקובץ הזה במקום בטוח, כי הוא מעניק הרשאת אדמין ל-App Distribution בפרויקט Firebase שלכם.
  4. אם יצרתם את האפליקציה אחרי 20 בספטמבר 2019, אפשר לדלג על השלב הזה: במסוף Google APIs, מפעילים את Firebase App Distribution API. כשמוצגת בקשה, בוחרים את הפרויקט שיש לו את אותו שם כמו הפרויקט ב-Firebase.

  5. מספקים או מאתרים את פרטי הכניסה לחשבון השירות:

    1. כדי להעביר ל-Gradle את המפתח של חשבון השירות, בקובץ build.gradle מגדירים את המאפיין serviceCredentialsFile לקובץ ה-JSON של המפתח הפרטי.

    2. כדי לאתר את פרטי הכניסה באמצעות ADC, מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS לנתיב של קובץ ה-JSON של המפתח הפרטי. לדוגמה: 

       export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/credentials/file.json

      למידע נוסף על אימות באמצעות ADC, קראו את המאמר איך מספקים פרטי כניסה לאפליקציה.

במאמר כניסה באמצעות ה-CLI של Firebase מוסבר איך מבצעים אימות של הפרויקט.

שלב 3. הגדרת מאפייני ההפצה

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

לדוגמה, כדי להפיץ את הגרסה המאוחדת release למבדקים, פועלים לפי ההוראות הבאות:

KotlinGroovy
import com.google.firebase.appdistribution.gradle.firebaseAppDistribution

android {

  // ...

  buildTypes {
      getByName("release") {
          firebaseAppDistribution {
              artifactType = "AAB"
              releaseNotesFile = "/path/to/releasenotes.txt"
              testers = "ali@example.com, bri@example.com, cal@example.com"
          }
      }
  }

  // ...
}
android {

  // ...

  buildTypes {
      release {
          firebaseAppDistribution {
              artifactType="AAB"
              releaseNotesFile="/path/to/releasenotes.txt"
              testers="ali@example.com, bri@example.com, cal@example.com"
          }
      }
  }

  // ...
}

אפשר להגדיר את App Distribution לסוגים של גרסאות build ולסוגים של מוצרים.

לדוגמה, כדי להפיץ גרסאות build של debug ו-release בגרסת הדגמה ובגרסה המלאה של המוצר, פועלים לפי ההוראות הבאות:

KotlinGroovy
import com.google.firebase.appdistribution.gradle.firebaseAppDistribution

android {

  // ...

  buildTypes {
      getByName("debug") {...}
      getByName("release") {...}
  }

  flavorDimensions += "version"
  productFlavors {
      create("demo") {
          dimension = "version"
          firebaseAppDistribution {
              releaseNotes = "Release notes for demo version"
              testers = "demo@testers.com"
          }
      }
      create("full") {
          dimension = "version"
          firebaseAppDistribution {
              releaseNotes = "Release notes for full version"
              testers = "full@testers.com"
          }
      }
  }

  // ...
}
android {

  // ...

  buildTypes {
      debug {...}
      release {...}
  }

  flavorDimensions "version"
  productFlavors {
      demo {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for demo version"
              testers="demo@testers.com"
          }
      }
      full {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for full version"
              testers="full@testers.com"
          }
      }
  }

  // ...
}

משתמשים בפרמטרים הבאים כדי להגדיר את ההפצה:

App Distribution פרמטרים של build
appId

מזהה האפליקציה ב-Firebase של האפליקציה. נדרש רק אם לא התקנתם את הפלאגין של שירותי Google ל-Gradle. מזהה האפליקציה מופיע בקובץ google-services.json או במסוף Firebase בדף General Settings (הגדרות כלליות). הערך בקובץ build.gradle מבטל את הערך שיוצא מהפלאגין google-services.

appId="1:1234567890:android:321abc456def7890"
serviceCredentialsFile

הנתיב לקובץ ה-JSON של המפתח הפרטי של חשבון השירות. חובה רק אם משתמשים באימות של חשבון שירות.
artifactType

מציין את סוג הקובץ של האפליקציה. אפשר להגדיר את הערך ל-"AAB" או ל-"APK".
artifactPath

הנתיב המוחלט לקובץ ה-APK או ה-AAB שרוצים להעלות.
releaseNotes או releaseNotesFile

נתוני הגרסה של גרסת ה-build הזו.

אפשר לציין את הערות המוצר ישירות או את הנתיב לקובץ טקסט פשוט.
testers או testersFile

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

אפשר לציין את הבודקים כרשימה של כתובות אימייל מופרדות בפסיקים:

testers="ali@example.com, bri@example.com, cal@example.com"

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

testersFile="/path/to/testers.txt"
groups או groupsFile

קבוצות הבודקים שאליהן רוצים לשלוח גרסאות build (מידע נוסף זמין במאמר ניהול בודקים). הקבוצות מצוינות באמצעות כינויים של קבוצות, שאפשר למצוא בכרטיסייה Testers במסוף App Distribution של Firebase.

אפשר לציין את הקבוצות כרשימה של כינויים של קבוצות, מופרדים בפסיקים:

groups="qa-team, android-testers"

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

groupsFile="/path/to/tester-groups.txt"
testDevices או testDevicesFile

סוגי ההפצה הבאים הם חלק מתכונת הבטא של הבודק האוטומטי.

מכשירי הבדיקה שבהם רוצים לפרוס גרסאות build (מידע נוסף זמין בקטע בדיקות אוטומטיות).

אפשר לציין את מכשירי הבדיקה כרשימה של מפרטי המכשירים, מופרדים בנקודה-פסיק:

testDevices="model=shiba,version=34,locale=en,orientation=portrait;model=b0q,version=33,locale=en,orientation=portrait"

לחלופין, אפשר לציין את הנתיב לקובץ שמכיל רשימה של מפרטי המכשיר המופרדים בנקודה-פסיק:

testDevicesFile="/path/to/testDevices.txt"
testUsername

שם המשתמש להתחברות אוטומטית לשימוש במהלך הבדיקות האוטומטיות.
testPassword או testPasswordFile

הסיסמה להתחברות אוטומטית לשימוש במהלך הבדיקות האוטומטיות.

לחלופין, אפשר לציין את הנתיב לקובץ טקסט פשוט שמכיל סיסמה:

testPasswordFile="/path/to/testPassword.txt"
testUsernameResource

שם המשאב של שדה שם המשתמש להתחברות אוטומטית, לשימוש במהלך בדיקות אוטומטיות.
testPasswordResource

שם המשאב של שדה הסיסמה לכניסה אוטומטית, לשימוש במהלך בדיקות אוטומטיות.
testNonBlocking

להריץ בדיקות אוטומטיות באופן אסינכרוני. תוצאות הבדיקה האוטומטית מוצגות במסוף Firebase.
stacktrace

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

שלב 4. הפצת האפליקציה לבודקים

  1. לבסוף, כדי לארוז את אפליקציית הבדיקה ולהזמין בודקים, יוצרים את היעדים BUILD-VARIANT ו-appDistributionUploadBUILD-VARIANT באמצעות מעטפת Gradle של הפרויקט, כאשר BUILD-VARIANT הוא סוג המוצר וה-build האופציונליים שהגדרתם בשלב הקודם. מידע נוסף על טעמי מוצרים זמין במאמר הגדרת וריאציות גרסאות build.

    לדוגמה, כדי להפיץ את האפליקציה באמצעות גרסת build ‏release, מריצים את הפקודה הבאה:

    ./gradlew bundleRelease appDistributionUploadRelease

    לחלופין, אם ביצעתם אימות באמצעות חשבון Google ולא סיפקתם פרטי כניסה בקובץ ה-build של Gradle, צריך לכלול את המשתנה FIREBASE_TOKEN:

    export FIREBASE_TOKEN=1/a1b2c3d4e5f67890
./gradlew --stop // Only needed for environment variable changes
./gradlew bundleRelease appDistributionUploadRelease

  2. אפשר גם לשנות את הערכים שהוגדרו בקובץ build.gradle על ידי העברת ארגומנטים של שורת הפקודה בפורמט --<property-name>=<property-value>. לדוגמה:

    • כדי להעלות גרסת build לניפוי באגים אל App Distribution:

      ./gradlew bundleDebug appDistributionUploadDebug
    --artifactType="AAB"

    • כדי להזמין בודקים נוספים או להסיר בודקים קיימים מהפרויקט ב-Firebase:

      ./gradlew appDistributionAddTesters
    --projectNumber=<project_number>
    --emails="anothertester@email.com, moretesters@email.com"
./gradlew appDistributionRemoveTesters
    --projectNumber=<project_number>
    --emails="anothertester@email.com, moretesters@email.com"

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

    אפשר גם לציין את הבדיקות באמצעות --file="/path/to/testers.txt" במקום --emails.

    המשימות appDistributionAddTesters ו-appDistributionRemoveTesters מקבלות גם את הארגומנטים הבאים:

    • projectNumber: מספר הפרויקט ב-Firebase.

    • serviceCredentialsFile: הנתיב לקובץ פרטי הכניסה לשירות Google. זהו אותו ארגומנט שמשמש את פעולת ההעלאה.

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

  • firebase_console_uri – קישור למסוף Firebase שבו מוצגת גרסה אחת. אפשר לשתף את הקישור הזה עם מפתחים אחרים בארגון.
  • testing_uri – קישור למהדורה בחוויית הבדיקה (אפליקציה מקורית ל-Android) שמאפשר לבודקים לראות את הערות המהדורה ולהתקין את האפליקציה במכשיר שלהם. כדי להשתמש בקישור, למבצע הבדיקה צריכה להיות גישה למהדורה.
  • binary_download_uri – קישור חתום שמוריד ומתקין ישירות את קובץ הבינארי של האפליקציה (קובץ APK או AAB). התוקף של הקישור יפוג אחרי שעה.

אחרי שתפיצו את ה-build, הוא יהיה זמין בלוח הבקרה App Distribution במסוף Firebase למשך 150 ימים (חמישה חודשים). 30 יום לפני שתוקף ה-build יפוג, תופיע הודעה על תפוגת התוקף במסוף וברשימה של ה-builds של הבוחן במכשיר הבדיקה שלו.

בודקים שלא הוזמנו לבדוק את האפליקציה יקבלו הזמנות באימייל כדי להתחיל, ובודקים קיימים יקבלו התראות באימייל על כך שגרסת build חדשה מוכנה לבדיקה (במדריך להגדרת בודקים מפורטות הוראות להתקנת אפליקציית הבדיקה). אתם יכולים לעקוב אחרי הסטטוס של כל בודק – אם הוא קיבל את ההזמנה ואם הוא הוריד את האפליקציה – במסוף Firebase.

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

השלבים הבאים