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


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

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

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

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

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

  • בודקים תכונות של חבילות אפליקציות כמו Play Feature Delivery ו-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, אתם צריכים להוסיף אותו. בסיום תהליך העבודה הזה, תהיה לכם אפליקציית Firebase ל-Android בפרויקט Firebase.

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

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

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

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

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

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

    1. במסוף Firebase, עוברים אל Project settings (הגדרות הפרויקט) ובוחרים בכרטיסייה Integrations (שילובים).

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

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

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

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

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

    Kotlin 

    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.3" apply false

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

    Groovy 

    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.3' 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:

    Kotlin 

    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")
}

    Groovy 

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

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

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

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

Kotlin 

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

  // ...
}

Groovy 

android {

  // ...

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

  // ...
}

אפשר להגדיר App Distribution עבור סוגי build ו-product flavors.

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

Kotlin 

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

  // ...
}

Groovy 

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 Services Gradle. אפשר למצוא את מזהה האפליקציה בקובץ google-services.json או במסוף Firebase בדף ההגדרות הכלליות. הערך בקובץ build.gradle מבטל את הערך שמופק מהתוסף google-services.

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

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

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

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

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

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

כתובות האימייל של הבודקים שרוצים להפיץ להם גרסאות build.

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

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

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

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

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

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

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

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

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

  1. לבסוף, כדי לארוז את אפליקציית הבדיקה ולהזמין בודקים, צריך ליצור את יעדי הבנייה BUILD-VARIANT ו-appDistributionUploadBUILD-VARIANT באמצעות Gradle wrapper של הפרויקט, כאשר BUILD-VARIANT הוא טעם המוצר האופציונלי וסוג הבנייה שהגדרתם בשלב הקודם. מידע נוסף על גרסאות מוצר זמין במאמר הגדרת וריאציות של 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) ומתקין אותו. התוקף של הקישור יפוג אחרי שעה.

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

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

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

השלבים הבאים