أداة تجميع

bundletool هي الأداة الأساسية التي يستخدمها "استوديو Android" و"المكوّن الإضافي لنظام Gradle المتوافق مع Android" وGoogle Play لإنشاء "مجموعة حزمات تطبيق Android". يمكن لأداة bundletool تحويل حِزمة تطبيق إلى حِزم APK مختلفة يتم نشرها على الأجهزة.

يتم إنشاء حِزم تطوير البرامج (SDK) لنظام التشغيل Android (ASB) وحِزم APK الخاصة بها باستخدام bundletool. تتوفّر أيضًا كأداة سطر أوامر، ما يتيح لك إنشاء حِزم التطبيقات وحِزم SDK بنفسك وإعادة إنشاء إصدار Google Play من جهة الخادم لحِزم APK الخاصة بتطبيقك أو حِزم APK الخاصة بحزمة SDK المفعَّلة في وقت التشغيل.

تنزيل bundletool

إذا لم يسبق لك إجراء ذلك، نزِّل bundletool من مستودع GitHub.

إنشاء حزمة تطبيق واختبارها

يمكنك استخدام "استوديو Android" أو أداة سطر الأوامر bundletool لإنشاء "حزمة تطبيق Android"، ثم اختبار إنشاء حِزم APK من حزمة التطبيق هذه.

إنشاء حِزمة تطبيق

استخدِم "استوديو Android" والمكوّن الإضافي لنظام Gradle المتوافق مع Android من أجل إنشاء حِزم تطبيقات Android وتوقيعها. ومع ذلك، إذا لم يكن استخدام بيئة التطوير المتكاملة خيارًا متاحًا، مثلاً لأنّك تستخدم خادمًا للإنشاء المتواصل، يمكنك أيضًا إنشاء حِزمة تطبيقك من سطر الأوامر وتوقيعها باستخدام jarsigner.

لمزيد من المعلومات حول إنشاء حِزم التطبيقات باستخدام bundletool، راجِع إنشاء حِزمة تطبيق باستخدام أداة Bundletool.

إنشاء مجموعة من حِزم APK من حِزمة تطبيقك

بعد إنشاء حِزمة تطبيق Android، اختبِر طريقة استخدام Google Play لها لإنشاء حِزم APK وطريقة عمل حِزم APK هذه عند نشرها على جهاز.

هناك طريقتان لاختبار حِزم التطبيق:

يوضّح هذا القسم كيفية استخدام 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

إبلاغ الوصف
--bundle=path (مطلوب) يحدّد هذا الخيار المسار إلى حزمة التطبيق التي أنشأتها باستخدام "استوديو Android". لمزيد من المعلومات، اطّلِع على إنشاء مشروعك.
--output=path (مطلوب) يحدّد اسم ملف الإخراج .apks الذي يحتوي على جميع عناصر حزمة APK الخاصة بتطبيقك. ولاختبار العناصر في هذا الملف على جهاز، اتّبِع الخطوات الواردة في القسم حول كيفية نشر حِزم APK على جهاز متصل.
--overwrite تستبدل أي ملف إخراج حالي بالمسار الذي تحدّده باستخدام الخيار --output. إذا لم تضمّن هذا الخيار وكان ملف الإخراج متوفّرًا، سيظهر لك خطأ في الإنشاء.
--aapt2=path تحدّد هذه السمة مسارًا مخصّصًا إلى AAPT2. يتضمّن bundletool تلقائيًا إصدارًا خاصًا به من أداة AAPT2.
--ks=path (اختياري) تحدّد هذه السمة مسار ملف تخزين المفاتيح المستخدَم في نشر التطبيق لتوقيع حِزم APK. في حال عدم تضمين هذا الخيار، ستتم محاولة توقيع حِزم APK باستخدام مفتاح توقيع تصحيح الأخطاء.bundletool
--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 تفعيل حِزمة تطبيقك لإجراء الاختبارات المحلية يتيح الاختبار المحلي إجراء دورات اختبار سريعة ومتكررة بدون الحاجة إلى تحميل التطبيق على خوادم Google Play.

للاطّلاع على مثال حول كيفية اختبار عمليات تثبيت الوحدات باستخدام العلامة --local-testing، راجِع اختبار عمليات تثبيت الوحدات محليًا.

نشر حِزم APK على جهاز متصل

بعد إنشاء مجموعة من حِزم APK، يمكن bundletool نشر المجموعة المناسبة من حِزم APK على جهاز متصل.

على سبيل المثال، إذا كان لديك جهاز متصل يعمل بالإصدار 5.0 من نظام التشغيل Android (المستوى 21 من واجهة برمجة التطبيقات) أو إصدار أحدث، يرسل bundletool حِزمة APK الأساسية وحِزم APK لوحدات الميزات وحِزم APK للإعدادات المطلوبة لتشغيل تطبيقك على هذا الجهاز. بدلاً من ذلك، إذا كان جهازك المتصل يعمل بالإصدار 4.4 من نظام التشغيل Android (المستوى 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

إبلاغ الوصف
--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، شاهِد الفيديو مجموعة حزمات التطبيق: اختبار الحِزم باستخدام أداة bundletool وPlay Console.