כלי Bundletool

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

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

הורדת bundletool

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

יצירה ובדיקה של App Bundle

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

בניית App Bundle

משתמשים ב-Android Studio ובפלאגין של Android Gradle כדי ליצור קובץ Android App Bundle ולחתום עליו. אבל אם לא תשתמשו בסביבת הפיתוח המשולבת (IDE) – לדוגמה, כי אתם משתמשים שרת build רציף (continuous delivery) — אפשר גם יצירת App Bundle משורת הפקודה ולחתום עליו באמצעות jarsigner.

למידע נוסף על יצירת קובצי App Bundle באמצעות bundletool, לראות יצירת App Bundle באמצעות Bundletool.

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

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

יש שתי דרכים לבדוק את ה-App Bundle:

• שימוש בכלי שורת הפקודה bundletool באופן מקומי.
• העלאת החבילה אל Play Console דרך Google Play באמצעות מסלול הפצה לבדיקה.

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

כשמערכת bundletool יוצרת חבילות APK מה-App Bundle, היא כוללת את חבילות APK בקונטיינר שנקרא ארכיון קבוצת APK, שבו נעשה שימוש בקובץ .apks לתוסף. כדי ליצור קבוצת APK לכל תצורות המכשירים שבהן האפליקציה שלך נתמכים מה-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

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

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

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

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

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

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

אם לא רוצים ליצור קבוצת חבילות APK לכל הגדרות המכשירים של האפליקציה אפשר לבנות חבילות APK שמטרגטות רק את התצורה של במכשיר באמצעות האפשרות --connected-device, כפי שמוצג בפקודה הבאה. אם יש לך כמה מכשירים מחוברים, מציינים מכשיר יעד באמצעות הכללת סימון --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

בניית App Bundle עם תלות של חבילת SDK (ניסיונית)

אפשר ליצור קובץ Android App Bundle עם תלות בקובץ Android SDK (ASB) משורת הפקודה ולחתום עליה באמצעות jarsigner.

כל מודול של App Bundle כולל קובץ מאגר נתונים זמני של פרוטוקול Module (.pb): runtime_enabled_sdk_config.pb. הקובץ הזה מכיל רשימה של ערכות SDK שמודול App Bundle תלוי בו. כדי לראות את ההגדרה המלאה של הקובץ, לראות את runtime_enabled_sdk_config.proto.

כדי ליצור App Bundle עם תלות של חבילת SDK, צריך לפעול לפי השלבים בקטע על פיתוח App Bundle באמצעות Bundletool והוספת קובץ runtime_enabled_sdk_config.pb ל-ZIP של כל מודול האפליקציה עם קוד ומשאבים שעברו הידור.

מספר שדות חשובים בקובץ runtime_enabled_sdk_config.pb:

• תקציר אישורים: תקציר SHA-256 של האישור של המפתח ששימשו לחתימה על חבילות ה-APK של ה-SDK. זה תואם לאישור קובץ SdkMetadata.pb בפורמט ארכיון של Android SDK.

• Resource Package ID: מזהה החבילה של כל המשאבים ב-SDK הזה. הן ממופות מחדש ליצירת חבילות APK להטמעת ה-SDK באפליקציה. כך אפשר להפעיל תאימות לאחור.

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

יצירת חבילות APK מ-App Bundle עם תלות של חבילת SDK (ניסיוני)

כדי ליצור חבילות APK מה-App Bundle, צריך לפעול לפי השלבים שמפורטים בקטע יצירת קבוצת חבילות APK מה-App Bundle או הקטע שעוסק יצירת קבוצת חבילות APK ספציפית למכשיר ולספק את הפקודה bundletool build-apks עם ערכות ה-SDK שהאפליקציה תלויה בהם. אפשר לספק את ערכות ה-SDK האלה בפורמט של חבילת SDK או ב-SDK פורמט העברה לארכיון.

אפשר לספק את ערכות ה-SDK כחבילות SDK על ידי הוספת הדגל --sdk-bundles, כפי ככה:

bundletool build-apks --bundle=app.aab --sdk-bundles=sdk1.asb,sdk2.asb \
    --output=app.apks

אפשר לספק את ערכות ה-SDK כארכיוני SDK על ידי הוספת הדגל --sdk-archives, ככה:

bundletool build-apks --bundle=app.aab --sdk-archives=sdk1.asar,sdk2.asar \
    --output=app.apks

יצירת חבילות APK מחבילת App Bundle עם תלות של חבילת SDK למכשירים שאין בהם תמיכה בספריית SDK

במכשירים מלפני Android 13 אין תמיכה בהתקנה של ספריות SDK או בהפעלה שלהן בסביבת זמן הריצה של ה-SDK. כלי Bundletool מסתיר את מורכבות התאימות לאחור יוצרות כמה וריאנטים של חבילת ה-APK המוגדרת מאותו App Bundle כאשר מריצים את bundletool build-apks עם האפשרות --sdk-bundles או --sdk-archives. הווריאציות המרובות מטורגטות למכשירים עם יכולות שונות:

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

בדומה לאופן שבו יוצרים חבילות APK לקובצי App Bundle ללא תלות ב-SDK, bundletool extract-apks ו-bundletool install-apks מחזירה קבוצה מסוננת של חבילות APK מהווריאנט הטוב ביותר של המכשיר המחובר או של המכשיר שסופק הגדרה

למקרי שימוש מתקדמים שבהם אתם רוצים רק ליצור פיצולי APK מארכיון SDK של אפליקציה ספציפית למכשירים ישנים יותר, אפשר להשתמש הפקודה bundletool build-sdk-apks-for-app באופן הבא:

bundletool build-sdk-apks-for-app --app-properties=app-properties.json \
    --sdk-archive=sdk.asar --output=sdk.apks

הקובץ app-properties צריך להכיל את השדות שמתוארים בקטע קובץ runtime_enabled_sdk_config.proto. זה מה שapp-properties נראה כך:

{
  "package_name": "com.my.app",
  "version_code": 1234,
  "min_sdk_version": 21,
  "resources_package_id": 0x7e
}

הפקודה bundletool build-sdk-apks-for-app יוצרת את קבוצת המשנה של האפליקציה חבילות APK שתואמות לתוכן ה-SDK בשם של חבילת האפליקציה. אפשר לשלב את חבילות ה-APK האלה עם חבילות APK אחרות שמכילות את תוכן האפליקציה. לדוגמה, אם אתה יכול לפתח אותם בנפרד ובאופן מצטבר, ומותקן יחד במכשיר שלא תומך בסביבת זמן הריצה של ה-SDK.

יצירה ובדיקה של חבילת SDK (ניסיונית)

אפשר להשתמש ב-bundletool כדי ליצור ASB ולבדוק את יצירת הדרושים להתקנה ולהפצה.

יצירה של חבילת SDK

אפשר ליצור את ה-ASB משורת הפקודה ולחתום עליו באמצעות jarsigner.

כדי ליצור חבילת SDK:

1. יצירת המניפסט והמשאבים של חבילת ה-SDK בפורמט פרוטו מבצעים את אותם השלבים כמו במקרה של קובץ App Bundle.

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

3. יוצרים קובץ SdkModulesConfig.pb.json ו-SdkBundleConfig.pb.json תואם לפורמט המתואר המפרט של חבילת Android SDK.

4. יוצרים ASB באמצעות הפקודה bundletool build-sdk-bundle, ככה:

bundletool build-sdk-bundle --sdk-bundle-config=SdkBundleConfig.pb.json \
    --sdk-modules-config=SdkModulesConfig.pb.json \
    --modules=base.zip --output=sdk.asb

הטבלה הבאה מתארת את הדגלים והאפשרויות השונים שניתן להגדיר כאשר באמצעות הפקודה bundletool build-sdk-bundle בצורה מפורטת יותר.

טבלה 3. האפשרויות של הפקודה bundletool build-sdk-bundle

יצירת חבילות APK מחבילת SDK

לאחר יצירת ה-ASB, ניתן לבדוק חבילת SDK באופן מקומי על ידי שיצרה את חבילות ה-APK שלה באמצעות הפקודה bundletool build-sdk-apks, כפי שמוצג את הקוד הבא:

bundletool build-sdk-apks --sdk-bundle=sdk.asb --output=sdk.apks

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

אם רוצים לפרוס את ה-ASB במכשיר, צריך לכלול גם את פרטי חתימה, כפי שמוצג בפקודה הבאה:

bundletool build-sdk-apks --sdk-bundle=sdk.asb --output=sdk.apks \
    --ks=keystore.jks \
    --ks-pass=file:/keystore.pwd \
    --ks-key-alias=KeyAlias \
    --key-pass=file:/key.pwd

הטבלה הבאה מתארת את הדגלים והאפשרויות השונים שניתן להגדיר כאשר באמצעות הפקודה bundletool build-sdk-apks בצורה מפורטת יותר.

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

פריסה, חילוץ ומדידה של הגודל של חבילות APK SDK

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

יצירת ארכיון SDK מחבילת SDK

אחרי שהעליתם את ה-ASB לערוץ ההפצה שלכם, ב-Google Play, ה-ASB מומר ל-Android SDK העברה לארכיון (.asar) להפצה למפתחי אפליקציות דרך Maven. לקבלת מידע נוסף פרטים על הפורמט, אפשר לעיין בקטע שעוסק מפרט הפורמט של SDK Archive

אחרי שתיצרו את ה-ASB, תוכלו לבדוק את המודל Archive SDK של Android Archive באופן מקומי באמצעות הפקודה bundletool build-sdk-asar, כמו שמוצגת בקוד הבא:

bundletool build-sdk-asar --sdk-bundle=sdk.asb --output=sdk.asar \
    --apk-signing-key-certificate=keycert.txt

הטבלה הבאה מתארת את הדגלים והאפשרויות השונים שניתן להגדיר כאשר באמצעות הפקודה bundletool build-sdk-asar בצורה מפורטת יותר.

טבלה 5. האפשרויות של הפקודה bundletool build-sdk-asar

פורמטים של SDK שמותאמים לזמן ריצה (ניסיוני)

ערכות SDK שתומכות בזמן ריצה כוללות שני פורמטים של קבצים ל-Android:

• חבילת ה-Android SDK (.asb), ששימשה לפרסום של SDK תואם זמן ריצה לחנויות אפליקציות.
• ארכיון ה-SDK של Android (.asar), שמשמש להפצה של ב-Maven ערכת SDK שתואמת לזמן ריצה.

הפורמט של חבילת Android SDK

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

חבילת Android SDK (ASB) היא קובץ ZIP חתום עם התוסף .asb הקוד והמשאבים של ה-SDK מאורגנים בו באופן דומה לסידור חיפוש ב-APK. ASB מכיל גם כמה קובצי תצורה שעוזרים יוצרים את חבילות ה-APK שניתנות להתקנה.

הרשימה הבאה מתארת חלק מקובצי ASB details:

• SdkBundleConfig.pb: קובץ תצורה בפורמט פרוטו, המכיל את הפונקציה רשימה של ערכות SDK תואמות זמן ריצה שה-SDK שלך תלוי בהן. לתוכנית המלאה בהגדרה, sdk_bundle_config.proto חדש.

• modules.resm: קובץ ZIP שמכיל את כל הנתונים הנדרשים כדי ליצור את חבילות APK מה-SDK.

• SdkModulesConfig.pb: קובץ תצורה בפורמט פרוטו. הקובץ הזה מכיל את השם, הגרסה ושם הסיווג של ה-SDK של נקודת הכניסה ל-SDK המסגרת SandboxedSdkProvider. להגדרה המלאה אפשר לעיין קובץ sdk_modules_config.proto.

• base/: המודול היחיד שמכיל את הקוד והמשאבים של ה-SDK.

  • manifest/: המניפסט של ה-SDK בפורמט פרוטו.
  • dex/: הקוד שעבר הידור בפורמט DEX. אפשר לספק כמה קובצי DEX.
  • res/, lib/, assets/: הספריות האלה זהות לאלה שבתוך APK רגיל. הנתיבים בספריות האלה נשמרים במהלך יצירת חבילות APK של SDK.
  • root/: בספרייה הזאת מאוחסנים קבצים שהועברו בהמשך לרמה הבסיסית (root) של חבילות ה-APK של ה-SDK. לדוגמה, הוא יכול לכלול משאבים מבוססי Java ערכת ה-SDK נטענת באמצעות Class.getResource() . הנתיבים בספרייה הזו נשמרים גם הם.

• BUNDLE-METADATA: ספרייה זו כוללת קובצי מטא נתונים שמכילים שימושי לכלים או לחנויות אפליקציות. קובצי מטא-נתונים כאלה יכולים כוללים את המיפויים של ProGuard ואת הרשימה המלאה של קובצי ה-DEX של ה-SDK. הקבצים בספרייה הזו לא נארזים בחבילות ה-APK של ה-SDK.

פורמט הארכיון של Android SDK

ארכיון Android SDK הוא פורמט ההפצה של ערכת SDK שתואמת לזמן ריצה ב- Maven. זהו קובץ ZIP עם סיומת הקובץ .asar. הקובץ מכיל את כל המידע שדרוש לכלים לבניית אפליקציות כדי ליצור קובץ Android App Bundle שתלוי ב-SDK שתומך בזמן ריצה.

הרשימה הבאה מתארת חלק מקובצי ארכיון של Android SDK details:

• SdkMetadata.pb: קובץ תצורה בפורמט פרוטו שמכיל את השם, הגרסה ותקציר האישורים של המפתח שמשמש לחתימה על חבילות APK שנוצרו בשביל ערכת ה-SDK הזו. להגדרה המלאה אפשר לעיין sdk_metadata.proto חדש.

• modules.resm: קובץ ZIP שמכיל את כל הנתונים הנדרשים כדי ליצור את חבילות APK מה-SDK. זהה לקובץ .resm חבילת Android SDK.

• AndroidManifest.xml: קובץ המניפסט של ה-SDK בפורמט טקסט XML.

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

למידע נוסף על השימוש ב-bundletool, אפשר לצפות App Bundle: בדיקת חבילות באמצעות Bundletool ו-Play Console.