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

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

Peter Conn

Joyce Toh

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

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

إذا كنت تخطط لاستخدام أداة فقاعات المحادثات لإنشاء مجموعة حزمات تطبيق Android (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، سيتم استخدام مفتاح التوقيع الذي تضيفه أداة 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" أو ثبِّته على الجهاز نفسه.
افتح تطبيق "أداة ربط مواد العرض"، وستظهر لك قائمة بجميع التطبيقات المثبّتة على جهاز حسب اسم الحزمة. فلترة القائمة حسب رقم تعريف التطبيق الذي اخترته في وقت سابق أثناء bubblewrap init والنقر على هذا الإدخال.
ستظهر لك صفحة تسرد توقيع تطبيقك ورابط مواد العرض الرقمية الذي تم إنشاؤه. انقر على يمكنك نسخ الأزرار أو مشاركتها في أسفل الصفحة لتصديرها كيفما تشاء (على سبيل المثال، الحفظ في Google Keep، إرساله إلى نفسك عبر البريد الإلكتروني).

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

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

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

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

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

# 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. الملف.