כלי Bundletool

‫bundletool הוא הכלי הבסיסי שמשמש את Android Studio, את הפלאגין של Android Gradle ואת Google Play ליצירת קובץ Android App Bundle. bundletool יכול להמיר חבילת אפליקציה לקובצי APK שונים שנפרסים במכשירים.

חבילות Android SDK ‏ (ASB) וקובצי ה-APK שלהן נוצרים באמצעות bundletool. הוא זמין גם ככלי לשורת הפקודה, כך שתוכלו ליצור בעצמכם חבילות App Bundle וחבילות SDK, וליצור מחדש את ה-build בצד השרת של Google Play של קובצי ה-APK של האפליקציה או של קובצי ה-APK של ה-SDK עם ההפעלה בזמן ריצה.

הורדת bundletool

אם עדיין לא עשיתם את זה, אתם יכולים להוריד את bundletool ממאגר GitHub.

פיתוח ובדיקה של קובץ App Bundle

אפשר להשתמש ב-Android Studio או בכלי bundletool משורת הפקודה כדי ליצור את קובץ Android App Bundle, ואז לבדוק את יצירת קובצי ה-APK מתוך קובץ ה-App Bundle הזה.

הרכבת קובץ App Bundle

משתמשים ב-Android Studio ובפלאגין Android Gradle כדי ליצור ולחתום על חבילת אפליקציות ל-Android. עם זאת, אם אי אפשר להשתמש בסביבת הפיתוח המשולבת – למשל, כי אתם משתמשים בשרת בנייה רציפה – אתם יכולים גם לבנות את חבילת האפליקציה משורת הפקודה ולחתום עליה באמצעות jarsigner.

מידע נוסף על יצירת קובצי App Bundle באמצעות bundletool זמין במאמר יצירת קובץ App Bundle באמצעות bundletool.

יצירת קבוצה של קובצי APK מ-App Bundle

אחרי שיוצרים את ה-App Bundle ל-Android, כדאי לבדוק איך Google Play משתמש בו כדי ליצור חבילות APK, ואיך חבילות ה-APK האלה מתנהגות כשפורסים אותן במכשיר.

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

בקטע הזה מוסבר איך להשתמש ב-bundletool כדי לבדוק את ה-App Bundle באופן מקומי.

כש-bundletool יוצר קובצי APK מ-App Bundle, הוא כולל את קובצי ה-APK שנוצרו במאגר שנקרא ארכיון של קבוצת APK, שמשתמש בסיומת הקובץ .apks. כדי ליצור קובץ APK Set לכל תצורות המכשירים שהאפליקציה תומכת בהן מתוך ה-App Bundle, משתמשים בפקודה bundletool build-apks, כמו שמוצג כאן:

bundletool build-apks --bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks

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

bundletool build-apks --bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks
--ks=/MyApp/keystore.jks
--ks-pass=file:/MyApp/keystore.pwd
--ks-key-alias=MyKeyAlias
--key-pass=file:/MyApp/key.pwd

בטבלה הבאה מפורטים הדגלים והאפשרויות השונים שאפשר להגדיר כשמשתמשים בפקודה bundletool build-apks:

טבלה 1. אפשרויות לפקודה bundletool build-apks

סימון תיאור
--bundle=path (חובה) מציין את הנתיב לחבילת האפליקציות שיצרתם באמצעות Android Studio. מידע נוסף מופיע במאמר בנושא יצירת פרויקט.
--output=path (חובה) מציין את השם של קובץ הפלט .apks שמכיל את כל פריטי המידע שנוצרים בתהליך פיתוח (Artifact) של ה-APK של האפליקציה. כדי לבדוק את פריטי המידע בקובץ הזה במכשיר, צריך לפעול לפי השלבים שבקטע בנושא פריסת קובצי APK במכשיר מחובר.
--overwrite מחליף קובץ פלט קיים בנתיב שצוין באמצעות האפשרות --output. אם לא כוללים את הדגל הזה וקובץ הפלט כבר קיים, מתקבלת שגיאת בנייה.
--aapt2=path מציין נתיב מותאם אישית ל-AAPT2. כברירת מחדל, bundletool כולל גרסה משלו של AAPT2.
--ks=path (אופציונלי) מציין את הנתיב למאגר המפתחות של הפריסה שמשמש לחתימה על קובצי ה-APK. אם לא תכללו את הדגל הזה, ‫bundletool ינסה לחתום על קובצי ה-APK שלכם באמצעות מפתח חתימה לניפוי באגים.
--ks-pass=pass:password
או
--ks-pass=file:/path/to/file		 מציינים את הסיסמה למאגר המפתחות. אם מציינים סיסמה בטקסט רגיל, צריך להוסיף לה את התו pass:. אם מעבירים את הנתיב לקובץ שמכיל את הסיסמה, צריך להוסיף לפניו את התו file:. אם מציינים מאגר מפתחות באמצעות הדגל --ks בלי לציין את --ks-pass,‏ bundletool יבקש סיסמה משורת הפקודה.
--ks-key-alias=alias מציינים את הכינוי של מפתח החתימה שרוצים להשתמש בו.
--key-pass=pass:password
או
--key-pass=file:/path/to/file		 מציינת את הסיסמה של מפתח החתימה. אם מציינים סיסמה בטקסט רגיל, צריך להוסיף לה את התו pass:. אם מעבירים את הנתיב לקובץ שמכיל את הסיסמה, צריך להוסיף לפניו את התו file:.

אם הסיסמה הזו זהה לסיסמה של חנות המפתחות עצמה, אפשר להשמיט את הדגל הזה.
--connected-device הפקודה גורמת לאפליקציה bundletool ליצור חבילות APK שמיועדות להגדרות של מכשיר מחובר. אם לא כוללים את הדגל הזה, ‫bundletool יוצר חבילות APK לכל תצורות המכשירים שהאפליקציה תומכת בהן.
--device-id=serial-number אם יש לכם יותר ממכשיר מחובר אחד, אתם יכולים להשתמש בדגל הזה כדי לציין את המזהה הסידורי של המכשיר שבו אתם רוצים לפרוס את האפליקציה.
--device-spec=spec_json מציינים נתיב לקובץ .json שמגדיר את תצורת המכשיר שרוצים לטרגט. מידע נוסף זמין בקטע בנושא יצירה ושימוש בקובצי JSON של מפרט המכשיר.
--mode=universal הגדרת המצב ל-universal. משתמשים באפשרות הזו אם רוצים bundletool ליצור קובץ APK יחיד שכולל את כל הקוד והמשאבים של האפליקציה, כך שקובץ ה-APK יהיה תואם לכל תצורות המכשירים שהאפליקציה תומכת בהן.

הערה: bundletool כולל רק מודולים של תכונות שמציינים <dist:fusing dist:include="true"/> במניפסט שלהם ב-APK אוניברסלי. מידע נוסף זמין במאמר בנושא מניפסט של מודול תכונות.

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

--local-testing ההרשאה מאפשרת לבצע בדיקות מקומיות של ה-App Bundle. בדיקה מקומית מאפשרת מחזורי בדיקה מהירים וחוזרים בלי צורך להעלות לשרתי Google Play.

דוגמה לאופן הבדיקה של התקנת מודול באמצעות הדגל --local-testing מופיעה במאמר בדיקה מקומית של התקנות מודולים.

פריסת חבילות APK למכשיר מחובר

אחרי שיוצרים קבוצה של קובצי APK, ‏ bundletool יכול לפרוס את השילוב הנכון של קובצי APK מהקבוצה הזו למכשיר מחובר.

לדוגמה, אם יש לכם מכשיר מחובר עם Android בגרסה 5.0 (רמת API‏ 21) ומעלה,‏ bundletool דוחף את קובץ ה-APK הבסיסי, קובצי ה-APK של מודול התכונות וקובצי ה-APK של ההגדרות שנדרשים להפעלת האפליקציה במכשיר הזה. לחלופין, אם במכשיר המחובר פועלת מערכת Android בגרסה 4.4 (API ברמה 20) ומטה, bundletool מחפש קובץ APK תואם מרובה כדי לפרוס אותו במכשיר.

כדי לפרוס את האפליקציה מקובץ APK Set, משתמשים בפקודה install-apks ומציינים את הנתיב של קובץ ה-APK Set באמצעות הדגל --apks=/path/to/apks, כמו שמוצג בפקודה הבאה. אם יש לכם כמה מכשירים מחוברים, צריך לציין מכשיר יעד באמצעות הוספת הדגל --device-id=serial-id.

‫
bundletool install-apks --apks=/MyApp/my_app.apks

יצירת קבוצה של חבילות APK ספציפיות למכשיר

אם אתם לא רוצים ליצור קבוצה של קובצי APK לכל תצורות המכשירים שהאפליקציה שלכם תומכת בהן, אתם יכולים ליצור קובצי APK שמיועדים רק לתצורה של מכשיר מחובר באמצעות האפשרות --connected-device, כמו שמוצג בפקודה הבאה. אם יש לכם כמה מכשירים מחוברים, אתם יכולים לציין מכשיר יעד באמצעות ה-flag‏ --device-id=serial-id.

bundletool build-apks --connected-device
--bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks

יצירה ושימוש בקובצי JSON של מפרט המכשיר

‫bundletool יכול ליצור חבילת APK שמיועדת לתצורת מכשיר שצוינה בקובץ JSON. כדי ליצור קובץ JSON למכשיר מחובר, מריצים את הפקודה הבאה:

bundletool get-device-spec --output=/tmp/device-spec.json

הכלי bundletool יוצר קובץ JSON למכשיר בספרייה של הכלי. אחר כך אפשר להעביר את הקובץ אל bundletool כדי ליצור קבוצה של קובצי APK שמיועדים רק לתצורה שמתוארת בקובץ ה-JSON, באופן הבא:

bundletool build-apks --device-spec=/MyApp/pixel2.json
--bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks

יצירה ידנית של קובץ JSON עם מפרט המכשיר

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

{
  "supportedAbis": ["arm64-v8a", "armeabi-v7a"],
  "supportedLocales": ["en", "fr"],
  "screenDensity": 640,
  "sdkVersion": 27
}

אחר כך אפשר להעביר את ה-JSON הזה לפקודה bundle extract-apks, כמו שמתואר בקטע הקודם.

איך מחלצים חבילות APK ספציפיות למכשיר מתוך חבילת APK קיימת

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

bundletool extract-apks
--apks=/MyApp/my_existing_APK_set.apks
--output-dir=/MyApp/my_pixel2_APK_set.apks
--device-spec=/MyApp/bundletool/pixel2.json

מדידת הגדלים המשוערים של הורדות קובצי APK בערכת APK

כדי למדוד את גודלי ההורדה המשוערים של קובצי APK בערכת APK, כפי שהם יועברו דחוסים דרך הרשת, משתמשים בפקודה get-size total:

bundletool get-size total --apks=/MyApp/my_app.apks

אפשר לשנות את ההתנהגות של הפקודה get-size total באמצעות הדגלים הבאים:

טבלה 2. אפשרויות לפקודה get-size total

סימון תיאור
--apks=path (חובה) מציין את הנתיב לקובץ הקיים של חבילת ה-APK שגודל ההורדה שלו נמדד.
--device-spec=path מציין את הנתיב לקובץ מפרט המכשיר (מתוך get-device-spec או שנוצר באופן ידני) שמשמש להתאמה. אפשר לציין נתיב חלקי כדי להעריך קבוצה של הגדרות.
--dimensions=dimensions מציין את המימדים שמשמשים לחישוב האומדנים של הגודל. המאפיין מקבל רשימה מופרדת בפסיקים של: SDK,‏ ABI,‏ SCREEN_DENSITY ו-LANGUAGE. כדי למדוד את כל המאפיינים, מציינים ALL.
--instant המדד הזה מודד את גודל ההורדה של חבילות ה-APK שמופעלות כאפליקציות ללא התקנה, ולא של חבילות ה-APK שניתנות להתקנה. כברירת מחדל, bundletool מודד את גודל ההורדה של חבילות ה-APK שניתנות להתקנה.
--modules=modules מציינים רשימה של מודולים שמופרדים בפסיקים בחבילת ה-APK שצריך לקחת בחשבון במדידה. הפקודה bundletool כוללת באופן אוטומטי את כל המודולים התלויים בקבוצה שצוינה. כברירת מחדל, הפקודה מודדת את גודל ההורדה של כל המודולים שהותקנו במהלך ההורדה הראשונה.

מקורות מידע נוספים

כדי לקבל מידע נוסף על השימוש ב-bundletool, אפשר לצפות בסרטון App Bundles: Testing bundles with bundletool and the Play Console.