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

عبر `keytool`

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

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

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