تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

مفاهيم Android (لمطوّري الويب)

Peter Conn

Joyce Toh

إذا كنت من مطوّري البرامج على الويب الذين يستخدمون Android وGoogle Play لأول مرة، هناك بعض التفاصيل التي يجب أن تكون على دراية بها. هناك بالفعل العديد من الموارد والوثائق ذات الصلة بهذا الموضوع (بفضل فريق Android) ولكن سنسلط الضوء هنا على بعض المفاهيم المهمة وكيفية ارتباطها بـ Bubblewrap.

مفتاح التحميل في مقابل مفتاح التوقيع

إذا كنت تخطِّط لاستخدام Bubble wrap لإنشاء تنسيق Android App Bundle (AAB) (ملاحظة: اعتبارًا من آب (أغسطس) 2021، سيطلب Google Play من جميع التطبيقات الجديدة استخدام تنسيق "مجموعة حزمات تطبيق Android") أو حزمة APK لتحميلها ونشرها على Google Play، عليك توقيع تطبيقك باستخدام مفتاح توقيع. تمنحك Google Play خيارين للتعامل مع هذا الأمر:

ميزة "توقيع التطبيق" من Play (يُنصح بها بشدة): ستتولى Google إدارة مفتاح توقيع تطبيقك وحمايته نيابةً عنك. ويستخدمها لتوقيع حِزم APK لتوزيعها. تستخدم ميزة "توقيع التطبيق" من Play مفتاحَين. "مفتاح توقيع التطبيق" الذي ستديره Google لك و "مفتاح التحميل" الذي تحتفظ به ويجب أن يبقى خاصًا بك. ويمكنك استخدام مفتاح التحميل لتوقيع تطبيقك لتحميله إلى Play Console. يتيح لك هذا النظام إعادة ضبط مفتاح التحميل في حال فقدانه أو اختراقه، وذلك من خلال التواصل مع فريق دعم Play. في الوقت الحالي، يتيح لك Google Play تحميل تطبيقك بتنسيق AAB أو حزمة APK:
- مجموعة حزمات تطبيق Android (AAB): عند تحميل تنسيق AAB إلى Play Console، يمكنك تأجيل عملية إنشاء حِزم APK وإنشائها إلى "متجر Google Play". عندما ينزِّل أحد المستخدمين تطبيقك ويثبّته، سيوزّعه Google Play عليه كملف APK موقَّع. ومن ثم، يجب أن يتم توقيع حِزم APK أيضًا من خلال Google Play. لذلك، إذا حمّلت تلقائيًا تطبيقك بتنسيق AAB إلى Play Console، سيُطلب منك استخدام ميزة "توقيع التطبيق" من Play.
- APK: باستخدام حِزم APK، يمكنك اختيار تفعيل ميزة "توقيع التطبيق" من Play. ننصحك بشدة بتفعيل ميزة "توقيع التطبيق" من Play لأنّها تعزّز أمان مفتاح التوقيع. كما أشرنا سابقًا، سيتطلب Google Play قريبًا تحميل جميع التطبيقات الجديدة بتنسيق AAB، لذا ننصحك بذلك بدلاً من تحميل حِزم APK.
إدارة مفتاح التوقيع الخاص بك: إذا اخترت إدارة مفتاحك الخاص بدون تفعيل ميزة "توقيع التطبيق" من Play، ستكون مسؤولاً تمامًا عن مفتاح توقيع تطبيقك. وعلى عكس ميزة "توقيع التطبيق" من Play، لا يمكن إعادة ضبط المفتاح في حال فقدان المفتاح. لذلك، يعني فقدان مفتاح توقيع التطبيق أنك ستفقد أيضًا القدرة على تحديث تطبيقك.

أثناء عملية إعداد bubblewrap init، عند الانتقال إلى القسم "توقيع معلومات المفتاح (5/5)"، سيُطلب منك إدخال "موقع تخزين المفاتيح" و"اسم المفتاح"، أو استخدام الإعدادات التلقائية. الموقع التلقائي لملف تخزين المفاتيح هو الملف android.keystore في دليل المشروع واسم المفتاح التلقائي هو android. إذا لم تعثر Bubblewrap على ملف تخزين حالي يتضمن اسم المفتاح هذا في الموقع، فستنشئ ملفًا لك وتطلب منك أيضًا كلمات المرور. دوِّن كلمات المرور التي أدخلتها بما أنك ستحتاج إليها أثناء عملية التصميم (bubblewrap build) والتي ستستخدم فيها المفتاح لتوقيع تطبيقك. وفي حال تفعيل ميزة "توقيع التطبيق" من Play، سيصبح مفتاح التوقيع الذي أنشأته ميزة "تغليف التطبيقات" واستخدِمها لتوقيع تطبيقك هو "مفتاح التحميل". وسواء اخترت استخدام المفتاح الذي تم إنشاؤه باستخدام "التفاف الفقاعات" كمفتاح للتوقيع أو التحميل، عليك حماية المفتاح والحفاظ على خصوصيته. ولا ننصح باستخدامه للتحكم في الإصدار. بدلاً من ذلك، قم بالحد من عدد الأفراد الذين لديهم إمكانية الوصول إليها.

روابط تنقل إلى مواد عرض رقمية

يجب استخدام "روابط مواد العرض الرقمية" لتوضيح العلاقة بين موقعك الإلكتروني وتطبيق Android. للتأكّد من أنّه تم بشكل صحيح التحقّق من تطبيق Android الذي أنشأته باستخدام Bubblewrap وتم تشغيله كنشاط ويب موثوق به (بدلاً من علامة تبويب Chrome المخصصة)، ستحتاج إلى إضافة المفتاح المناسب إلى ملف assetlinks.json الخاص بك. بعد ذلك، حمِّله إلى موقعك الإلكتروني على .well-known/assetlinks.json (حسب الجذر). يجب أن يكون ملف assetlinks.json بالتنسيق التالي:

[{
 "relation": ["delegate_permission/common.handle_all_urls"],
 "target": {
   "namespace": "android_app",
   "package_name": "com.your.package_name",
   "sha256_cert_fingerprints": [
     "XX:XX:XX:..."
   ]
 }
}]

الحصول على الملف المرجعي لشهادة SHA256

لإنشاء ملف assetlinks.json، ستحتاج إلى الملف المرجعي لشهادة SHA 256 المرتبط بمفتاح توقيع تطبيقك. تجدر الإشارة إلى أنّ بصمات الأصابع المرتبطة بمفاتيح التوقيع والتحميل ستكون مختلفة. ومن المهم وضع هذا التمييز في الاعتبار، خاصةً إذا لاحظت أن تطبيقك يتم تشغيله كعلامة تبويب مخصّصة في Chrome (مع ظهور شريط المتصفّح). بعد ذلك، من المحتمل أنّ ملف assetlinks.json لا يحتوي على الملف المرجعي للمفتاح المناسب.

من المفيد إضافة الملف المرجعي لشهادة التوقيع وتحميله في ملف assetlinks.json لتصحيح أخطاء تطبيقك محليًا بسهولة أكبر. راجِع إضافة المزيد من المفاتيح أدناه للاطّلاع على مزيد من المعلومات حول كيفية إضافة المفتاحَين في ملف assetlinks.json.

هناك طريقتان مختلفتان للحصول على الملف المرجعي وسيتم عرضهما بالتفصيل في الأقسام التالية. يجب أن تمنحك جميعًا بصمات الإصبع نفسها، لذا لا تتردد في اختيار الطريقة الأكثر ملاءمة.

من خلال Play Console

قد يكون لديك مفتاح أو مفتاحَين، بناءً على ما إذا فعّلت ميزة "توقيع التطبيق" من Play أم لا. لاسترداد بصمة إصبع SHA256 المناسبة لكل مفتاح:

انتقِل إلى Play Console.
اختيار التطبيق الذي يهمّك
في قائمة التنقّل على يمين الصفحة، ضمن الإصدار، انتقِل إلى الإعداد -> سلامة التطبيق.
انسخ خوارزمية SHA256 للمفتاح المناسب:

استرداد الملف المرجعي لشهادة SHA256 المناسبة لمفتاح التوقيع أو التحميل

مفتاح التوقيع: انسخ الملف المرجعي لخوارزمية SHA256 التي تخص "شهادة مفتاح توقيع التطبيق". ستتوافق بصمة الإصبع هذه مع تطبيقك في حال تنزيله من "متجر Google Play" لأنّ Google Play يوزّع تطبيقك الموقَّع باستخدام مفتاح التوقيع.
مفتاح التحميل: انسخ الملف المرجعي لخوارزمية SHA256 في "شهادة مفتاح التحميل". ستتوافق بصمة الإصبع مع تطبيقك في حال تثبيته محليًا (عبر ADB عبر USB على سبيل المثال). تم إنشاء حزمة APK هذه (على جهازك المحلي) بواسطة Bubblewrap، ولذلك تم توقيعها بواسطة المفتاح الذي أنشأته لك أيضًا (أثناء إعداد init). قد يكون هذا المفتاح هو مفتاح التوقيع لتطبيقك المثبَّت على الجهاز، ولكنه يصبح في الواقع "مفتاح التحميل" بعد نشر تطبيقك من خلال Play.

عبر `keytool`

keytool هي أداة مفتاح وإدارة الشهادات. يمكنك استخدام أداة المفاتيح لاستخراج بصمة إصبع SHA 256 المرتبطة بملف APK أو "التفاف فقاعة AAB" الذي تم إنشاؤه. يُرجى العِلم أنّ بصمة الإصبع هذه مخصّصة لمفتاح التوقيع المحلي، وإذا حمّلت تطبيقك إلى Play وفعّلت ميزة "توقيع التطبيق" من Play، سيصبح هذا المفتاح هو "مفتاح التحميل".

keytool -printcert -jarfile [path to APK or AAB] | grep SHA256

عبر "أداة ربط مواد العرض"

هناك طريقة أخرى للحصول على ملف "روابط مواد العرض الرقمية" الصحيح لتطبيقك، وهي استخدام أداة روابط مواد العرض:

ثبِّت أداة رابط مواد العرض من "متجر Play".
على الجهاز نفسه، يمكنك تنزيل تطبيقك من "متجر Google Play" أو تثبيته على الجهاز.
افتح تطبيق "أداة ربط مواد العرض"، وستظهر لك قائمة بجميع التطبيقات المثبَّتة على جهازك حسب اسم الحزمة. يمكنك فلترة القائمة حسب رقم تعريف التطبيق الذي اخترته سابقًا في bubblewrap init والنقر على هذا الإدخال.
ستظهر لك صفحة تتضمّن توقيع تطبيقك ورابط إلى مادة عرض رقمية تم إنشاؤه. انقر على الزر "نسخ" أو "مشاركة" في الجزء السفلي لتصديره كيفما تشاء (على سبيل المثال، حفظ في Google Keep، أو إرساله إلى نفسك بالبريد الإلكتروني).

تنطبق الفكرة نفسها كما في السابق باستخدام مفاتيح التوقيع أو التحميل. إذا ثبَّت تطبيقك من "متجر Google Play"، ستحصل لك "أداة رابط مواد العرض" على بصمة الإصبع لمفتاح توقيع تطبيقك. وفي حال تثبيت التطبيق مباشرةً من جهازك المحلي، تكون بصمة الإصبع هي للمفتاح الذي تم إنشاؤه من خلال ميزة "تغليف الفقاعات".

التأكّد من إمكانية الوصول إلى ملف رابط مواد العرض

والآن بعد أن حمّلته، تأكد من أنه يمكنك الوصول إلى ملف رابط مادة العرض في متصفح. تأكَّد من أنّ السمة https://example.com/.well-known/assetlinks.json يمكنها الوصول إلى الملف الذي حمّلته للتو.

المواقع الإلكترونية التي تستند إلى Jekyll

إذا تم إنشاء موقعك الإلكتروني بواسطة Jekyll (مثل صفحات GitHub)، عليك إضافة سطر من الإعدادات بحيث يتم تضمين دليل .well-known في الناتج. يمكنك الحصول على مزيد من المعلومات حول هذا الموضوع في مركز مساعدة GitHub. أنشئ ملفًا باسم _config.yml في جذر موقعك الإلكتروني (أو أضِفه إليه إذا كان متوفرًا) وأدخِل:

# Folders with dotfiles are ignored by default.
include: [.well-known]

إضافة المزيد من المفاتيح

يمكن أن يحتوي ملف "رابط الأصول الرقمية" على أكثر من تطبيق واحد، ويمكن أن يحتوي لكل تطبيق على أكثر من مفتاح واحد. على سبيل المثال، لإضافة مفتاح ثانٍ، ما عليك سوى استخدام أداة رابط مادة العرض لتحديد المفتاح وإضافته كإدخال ثانٍ. الرمز البرمجي في Chrome الذي يحلّل تنسيق JSON هذا صارمًا تمامًا، لذا يُرجى التأكد من عدم إضافة فاصلة إضافية عن طريق الخطأ في نهاية القائمة.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
},{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
}]

تحديد المشاكل وحلّها

يسجِّل Chrome سبب تعذُّر إثبات ملكية "روابط مواد العرض الرقمية" ويمكنك الاطّلاع على السجلّات على جهاز Android باستخدام adb logcat. إذا كنت تطوِّر نظام التشغيل على نظام التشغيل Linux أو Mac، يمكنك الاطّلاع على السجلّات ذات الصلة من جهاز متصل باستخدام:

> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

على سبيل المثال، إذا رأيت الرسالة Statement failure matching fingerprint.، عليك استخدام "أداة رابط مواد العرض" للاطّلاع على توقيع تطبيقك والتأكّد من أنّه يتطابق مع ذلك الوارد في ملف assetlinks.json.