ابزار بسته بندی

bundletool ابزار زیربنایی است که Android Studio، پلاگین Android Gradle و Google Play برای ساخت یک Android App Bundle استفاده می کنند. bundletool می‌تواند یک بسته برنامه را به فایل‌های APK مختلفی که در دستگاه‌ها مستقر می‌شوند تبدیل کند.

بسته‌های Android SDK (ASB) و فایل‌های APK آن‌ها با bundletool ساخته شده‌اند. همچنین به عنوان یک ابزار خط فرمان در دسترس است، بنابراین می‌توانید بسته‌های برنامه و بسته‌های SDK را خودتان بسازید و ساختار سمت سرور Google Play مربوط به APKهای برنامه یا APKهای SDK با قابلیت زمان اجرا را دوباره ایجاد کنید.

bundletool دانلود کنید

اگر قبلاً این کار را نکرده‌اید، bundletool از مخزن GitHub دانلود کنید.

یک بسته نرم افزاری بسازید و آزمایش کنید

می‌توانید از Android Studio یا ابزار خط فرمان bundletool برای ساختن Android App Bundle خود و سپس آزمایش تولید APK از این بسته برنامه استفاده کنید.

یک بسته نرم افزاری بسازید

از Android Studio و افزونه Android Gradle برای ساخت و امضای یک Android App Bundle استفاده کنید. با این حال، اگر استفاده از IDE یک گزینه نیست - برای مثال، به دلیل اینکه از یک سرور ساخت مداوم استفاده می‌کنید، می‌توانید بسته نرم افزاری خود را از خط فرمان بسازید و با استفاده از jarsigner آن را امضا کنید.

برای اطلاعات بیشتر در مورد ساخت بسته نرم افزاری با bundletool ، به ساخت بسته نرم افزاری با استفاده از bundletool مراجعه کنید.

مجموعه ای از فایل های APK را از بسته برنامه خود ایجاد کنید

پس از ساختن Android App Bundle، آزمایش کنید که Google Play چگونه از آن برای تولید فایل‌های APK استفاده می‌کند و چگونه آن فایل‌های APK هنگام استقرار در دستگاهی رفتار می‌کنند.

دو روش وجود دارد که می توانید بسته برنامه خود را آزمایش کنید:

• از ابزار خط فرمان bundletool به صورت محلی استفاده کنید.
• باندل خود را از طریق Google Play با استفاده از یک آهنگ آزمایشی در Play Console آپلود کنید .

این بخش نحوه استفاده از bundletool را برای آزمایش بسته نرم افزاری خود به صورت محلی توضیح می دهد.

وقتی bundletool فایل‌های APK را از بسته برنامه شما تولید می‌کند، فایل‌های APK تولید شده را در محفظه‌ای به نام بایگانی مجموعه APK که از پسوند فایل .apks استفاده می‌کند، قرار می‌دهد. برای ایجاد یک مجموعه APK برای همه پیکربندی‌های دستگاهی که برنامه شما از بسته برنامه شما پشتیبانی می‌کند، از دستور 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

ساخت یک بسته برنامه با وابستگی بسته نرم افزاری SDK (تجربی)

می‌توانید App Bundle Android خود را با وابستگی Android SDK Bundle (ASB) از خط فرمان بسازید و با استفاده از jarsigner آن را امضا کنید.

هر ماژول بسته برنامه شامل یک فایل بافر پروتکل ماژول ( .pb ) است: runtime_enabled_sdk_config.pb . این فایل حاوی لیستی از SDKهایی است که یک ماژول بسته نرم افزاری به آنها وابسته است. برای تعریف کامل این فایل، فایل runtime_enabled_sdk_config.proto را ببینید.

برای ساختن یک بسته نرم افزاری با وابستگی بسته SDK، مراحل بخش مربوط به ساخت بسته نرم افزاری با استفاده از bundletool را دنبال کنید و یک فایل runtime_enabled_sdk_config.pb را با کد و منابع کامپایل شده به فایل فشرده هر ماژول برنامه اضافه کنید.

برخی از فیلدهای قابل توجه در فایل runtime_enabled_sdk_config.pb :

• خلاصه گواهی: خلاصه SHA-256 گواهی برای کلید مورد استفاده برای امضای فایل‌های APK SDK. این مربوط به گواهی موجود در فایل SdkMetadata.pb در قالب Android SDK Archive است.

• شناسه بسته منابع: شناسه بسته ای که همه منابع در این SDK هنگام تولید فایل‌های APK برای جاسازی SDK در برنامه به آن بازنگری می‌شوند. این امکان سازگاری با عقب را فراهم می کند.

یک SDK فقط می تواند در یک ماژول ظاهر شود. اگر چندین ماژول به یک SDK وابسته هستند، این وابستگی باید حذف شود و به ماژول پایه منتقل شود. ماژول های مختلف نمی توانند به نسخه های مختلف SDK وابسته باشند.

ایجاد فایل‌های APK از یک بسته برنامه با وابستگی به بسته نرم افزاری SDK (تجربی)

برای تولید فایل‌های APK از بسته برنامه خود، مراحل بخش مربوط به تولید مجموعه‌ای از APK از بسته برنامه خود یا بخش مربوط به تولید مجموعه‌ای از APK مخصوص دستگاه را دنبال کنید و دستور bundletool build-apks با SDK‌های برنامه ارائه کنید. بستگی دارد. این SDK ها را می توان در قالب SDK bundle یا SDK Archive ارائه کرد.

می‌توانید با افزودن پرچم --sdk-bundles SDK‌ها را به‌صورت بسته‌های SDK ارائه کنید، به شرح زیر:

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

با افزودن پرچم --sdk-archives به صورت زیر می توانید SDK ها را به عنوان بایگانی SDK ارائه کنید:

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

ایجاد فایل‌های APK از یک بسته برنامه با وابستگی به بسته SDK برای دستگاه‌های بدون پشتیبانی از کتابخانه SDK

دستگاه‌های قبل از Android 13 از نصب کتابخانه‌های SDK یا اجرای آن‌ها در زمان اجرا SDK پشتیبانی نمی‌کنند. هنگامی که bundletool build-apks با گزینه --sdk-bundles یا --sdk-archives اجرا می کنید، Bundletool پیچیدگی سازگاری رو به عقب را پنهان می کند و چندین گونه از مجموعه APK شما را از یک بسته برنامه مشابه تولید می کند. انواع مختلف دستگاه هایی با قابلیت های مختلف را هدف قرار می دهند:

• یک نوع برای دستگاه‌های جدیدتر وجود دارد، که در آن SDK به‌عنوان بسته‌ای جداگانه از برنامه نصب می‌شود و فایل‌های APK برنامه حاوی محتوای SDK نیستند.
• یک یا چند نوع برای دستگاه‌های قدیمی‌تر وجود دارد که در آن فایل‌های APK SDK به‌عنوان تقسیم‌های APK اضافی به مجموعه APK برنامه اضافه می‌شوند. فایل‌های APK SDK متعلق به بسته برنامه هستند. در این حالت، زمان اجرا SDK در زمان اجرا برنامه روی دستگاه شبیه سازی می شود.

مشابه نحوه تولید فایل‌های APK برای بسته‌های برنامه بدون وابستگی به 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 را در قالب پروتو با دنبال کردن همان مراحلی که برای یک بسته برنامه وجود دارد ایجاد کنید .

2. کد و منابع کامپایل شده SDK خود را مانند یک ماژول برنامه در یک فایل فشرده اصلی بسته بندی کنید .

3. یک فایل SdkModulesConfig.pb.json و یک فایل SdkBundleConfig.pb.json ایجاد کنید که با فرمت توضیح داده شده در مشخصات Android SDK Bundle مطابقت دارد.

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 شما تولید می‌کند، این ابزار شامل APKS در محفظه‌ای به نام بایگانی مجموعه 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 به یک بایگانی SDK Android ( .asar ) تبدیل می شود تا از طریق Maven برای توسعه دهندگان برنامه توزیع شود. برای جزئیات بیشتر در مورد قالب، به بخش مربوط به مشخصات قالب بایگانی SDK مراجعه کنید.

پس از ساختن ASB، می‌توانید با استفاده از دستور bundletool build-sdk-asar تولید آرشیو SDK Android را به صورت محلی آزمایش کنید، همانطور که در کد زیر نشان داده شده است:

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 SDK ( .asb ​​)، برای انتشار SDK فعال با زمان اجرا در فروشگاه های برنامه استفاده می شود.
• بایگانی SDK Android ( .asar )، برای توزیع SDK فعال با زمان اجرا در Maven استفاده می‌شود.

قالب Android SDK Bundle

یک SDK Bundle یک قالب انتشار برای SDK های فعال در زمان اجرا است. این شامل تمام کدها و منابع SDK، از جمله کدهای هر کتابخانه ای است که SDK به آنها وابسته است. این شامل کد و منابع سایر SDK های فعال در زمان اجرا که SDK به آنها وابسته است، نمی شود.

بسته نرم افزاری Android SDK (ASB) یک فایل فشرده امضا شده با پسوند .asb ​​است. کد SDK و منابع مشابه آنچه در یک APK پیدا می کنید در آن سازماندهی شده است. یک ASB همچنین حاوی چندین فایل پیکربندی است که به تولید APK های قابل نصب کمک می کند.

لیست زیر برخی از فایل های ASB را با جزئیات بیشتری شرح می دهد:

• SdkBundleConfig.pb : یک فایل پیکربندی در قالب پروتو، حاوی لیستی از SDK های فعال در زمان اجرا که SDK شما به آن وابسته است. برای تعریف کامل، فایل sdk_bundle_config.proto را ببینید.

• modules.resm : یک فایل فشرده حاوی تمام داده های مورد نیاز برای تولید 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/ : این دایرکتوری فایل هایی را ذخیره می کند که بعداً به ریشه فایل های APK SDK منتقل می شوند. به عنوان مثال، ممکن است شامل منابع مبتنی بر جاوا باشد که SDK شما با استفاده از متد Class.getResource() بارگیری می کند. مسیرهای داخل این فهرست نیز حفظ می شوند.

• BUNDLE-METADATA : این فهرست شامل فایل‌های فراداده است که حاوی اطلاعات مفید برای ابزارها یا فروشگاه‌های برنامه است. چنین فایل های ابرداده ای ممکن است شامل نگاشت های ProGuard و لیست کامل فایل های DEX SDK شما باشد. فایل‌های این فهرست در فایل‌های APK SDK شما بسته‌بندی نمی‌شوند.

قالب Android SDK Archive

Android SDK Archive فرمت توزیع یک SDK فعال در زمان اجرا در Maven است. این یک فایل فشرده با پسوند فایل .asar است. این فایل حاوی تمام اطلاعاتی است که ابزارهای ساخت برنامه برای ایجاد یک بسته نرم افزاری Android که به SDK فعال در زمان اجرا شما نیاز دارد، نیاز دارد.

فهرست زیر برخی از فایل‌های بایگانی SDK Android را با جزئیات بیشتری شرح می‌دهد:

• SdkMetadata.pb : یک فایل پیکربندی در قالب پروتو حاوی نام SDK، نسخه و خلاصه گواهی برای کلید مورد استفاده برای امضای APKهای تولید شده برای این SDK. برای تعریف کامل، فایل sdk_metadata.proto را ببینید.

• modules.resm : یک فایل فشرده حاوی تمام داده های مورد نیاز برای تولید APK ها از SDK. این همان فایل .resm در بسته نرم افزاری Android SDK است.

• AndroidManifest.xml : فایل مانیفست SDK در قالب متنی XML.

منابع اضافی

برای کسب اطلاعات بیشتر درباره استفاده از bundletool ، App Bundles: Testing bundles با bundletool و Play Console را تماشا کنید.