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

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

Peter Conn

Joyce Toh

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

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

إذا كنت تخطّط لاستخدام Bubblewrap لإنشاء مجموعة حزمات تطبيق Android (ملاحظة: اعتبارًا من آب (أغسطس) 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 موقَّعة. لذلك، يجب أن يُوقِّع Google Play أيضًا على حِزم APK. لذلك، إذا حمّلت تطبيقك كحزمة 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، يصبح مفتاح التوقيع الذي أنشأه Bubblewrap واستخدمه لتوقيع تطبيقك هو "مفتاح التحميل". سواء اخترت استخدام المفتاح الذي أنشأته باستخدام Bubblewrap كمفتاح توقيع أو مفتاح تحميل، عليك الحفاظ على سرية المفتاح. لا ننصحك بإرسالها إلى نظام التحكّم بالإصدارات. بدلاً من ذلك، يمكنك الحد من عدد الأشخاص الذين يمكنهم الوصول إليه.

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

يجب استخدام روابط مواد العرض الرقمية للإشارة إلى العلاقة بين موقعك الإلكتروني وتطبيق 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 هي أداة لإدارة مفاتيح التشفير والشهادات. يمكنك استخدام أداة keytool لاستخراج الملف المرجعي SHA 256 المرتبط بملف APK أو حزمة AAB Bubblewrap التي تم إنشاؤها. يُرجى العِلم أنّ بصمة الإصبع هذه مخصّصة لمفتاح التوقيع على الجهاز، وإذا uploadedتحميلت تطبيقك إلى Play وتفعّلت ميزة "توقيع التطبيق" من Play، سيصبح هذا المفتاح "مفتاح التحميل".

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

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

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

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

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

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

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

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

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

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

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

يمكن أن يحتوي ملف Digital Asset Link على أكثر من تطبيق واحد، ويمكن أن يحتوي كل تطبيق على أكثر من مفتاح واحد. على سبيل المثال، لإضافة مفتاح ثانٍ، ما عليك سوى استخدام أداة ربط مواد العرض لتحديد المفتاح وإضافته كإدخال ثانٍ. إنّ الرمز البرمجي في 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.