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

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

بالنسبة إلى "روابط التطبيق الديناميكية" في الإصدار 15 من نظام التشغيل Android والإصدارات الأحدث، يُستخدَم ملف assetlinks.json أيضًا لتحديد إعدادات القواعد الديناميكية، مثل أدوات مطابقة الأنماط للمسار والجزء ومَعلمات طلب البحث. ستسترد أجهزة Android التي تعمل بالإصدار 15 (المستوى 35 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث من نظام التشغيل Android والتي تم تثبيت خدمات Google عليها الملف بشكل دوري وتدمج الإعدادات الديناميكية مع الإعدادات الثابتة في بيان التطبيق.

يوضّح هذا الدليل كيفية إعداد ملف assetlinks.json ونشره على موقعك الإلكتروني. إذا كنت تفضّل ذلك، يمكنك إنشاء ملف assetlinks.json من أداة "الروابط لصفحات معيّنة في Play" أو "مساعِد روابط التطبيقات" في "استوديو Android". لمزيد من المعلومات، يُرجى الاطّلاع على أدوات المطوّرين لروابط التطبيقات.

تحديد عمليات الربط بالمواقع الإلكترونية

يجب نشر ملف JSON لروابط التنقل إلى مواد العرض الرقمية على موقعك الإلكتروني للإشارة إلى تطبيقات Android المرتبطة بالموقع الإلكتروني وإثبات صحة أغراض عناوين URL للتطبيق. يستخدم ملف JSON الحقول التالية لتحديد التطبيقات المرتبطة:

• package_name: معرّف التطبيق المُعلن عنه في ملف build.gradle الخاص بالتطبيق
• ‫sha256_cert_fingerprints: تمثّل هذه السمة الملفات المرجعية لمعيار SHA256 الخاص بشهادة توقيع تطبيقك. يمكنك استخدام الأمر التالي لإنشاء بصمة الإصبع باستخدام أداة keytool في Java:

keytool -list -v -keystore my-release-key.keystore

• يتيح هذا الحقل استخدام بصمات متعددة يمكن استخدامها لتوفير إصدارات مختلفة من تطبيقك، مثل إصدارات تصحيح الأخطاء وإصدارات الإنتاج. إذا كنت تستخدم خدمة توقيع تطبيق Play لتطبيقك، لن تتطابق عادةً بصمة الشهادة التي يتم إنتاجها من خلال تنفيذ keytool محليًا مع تلك الموجودة على أجهزة المستخدمين. يمكنك التأكّد مما إذا كنت تستخدم ميزة "توقيع تطبيق Play" لتطبيقك في حساب المطوِّر الخاص بك على Play Console ضمن Release > Setup > App signing. وفي حال استخدامها، ستعثر أيضًا على مقتطف JSON الصحيح لـ "روابط التنقل إلى مواد العرض الرقمية" لتطبيقك في الصفحة نفسها.

يمنح ملف المثال التالي assetlinks.json تطبيق Android com.example حقوق فتح الروابط:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

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

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

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

قد تتعامل تطبيقات مختلفة مع روابط لموارد مختلفة ضمن مضيف الويب نفسه. على سبيل المثال، قد يعرّف التطبيق 1 فلتر أهداف لـ https://example.com/articles، وقد يعرّف التطبيق 2 فلتر أهداف لـ https://example.com/videos.

ربط مواقع إلكترونية متعددة بتطبيق واحد

يمكن أن تعلن مواقع إلكترونية متعددة عن ارتباطها بالتطبيق نفسه في ملفات assetlinks.json الخاصة بها. تعرض قوائم الملفات التالية مثالاً على كيفية تعريف الربط بين example.com وexample.net وapp1. تعرض القائمة الأولى ارتباط example.com بالتطبيق app1:

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

تعرض البطاقة التالية ربط example.net بتطبيق app1. يختلف فقط الموقع الذي تتم فيه استضافة هذه الملفات (.com و .net):

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

ضبط القواعد الديناميكية

تتيح لك "روابط التطبيق الديناميكية" في الإصدار 15 من نظام التشغيل Android والإصدارات الأحدث استخدام قواعد مطابقة الروابط لصفحات في التطبيق من جهة الخادم، وتعمل هذه القواعد مع القواعد التي حدّدتها بشكل ثابت في بيان تطبيقك. ملف assetlinks.json هو المكان الذي تحدّد فيه القواعد الديناميكية. يمكنك اختياريًا تضمين هذه المعلومات.

ستستردّ أجهزة Android التي تعمل بالإصدار 15 (المستوى 35 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث من نظام التشغيل Android والتي تم تثبيت خدمات Google عليها هذا الملف بشكل دوري من الخادم وتدمج إعدادات القواعد الديناميكية مع الإعدادات الثابتة في بيان التطبيق. في ما يلي مثال على ملف assetlinks.json يتضمّن قواعد ديناميكية:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

النقاط الرئيسية حول الرمز

• تضيف "روابط التطبيق الديناميكية" إضافة علاقة جديدة في Digital Asset Links باسم dynamic_app_link_components، وهي المكان الذي يمكنك فيه ضبط القواعد الديناميكية.
• يمكن أن تتضمّن القواعد الديناميكية أدوات مطابقة الأنماط للمسار والجزء ومَعلمات طلب البحث.
• يمكنك أيضًا وضع علامة "مستبعد" على أي أداة مطابقة أنماط، حتى لا تفتح عناوين URL المطابقة تطبيقك.
• يعرض هذا المثال أمثلة على أدوات المطابقة للمسار ("/") والجزء ("#") ومَعلمات طلب البحث ("?")، بالإضافة إلى أدوات المطابقة المستبعَدة ("exclude").
• إذا كانت أي من الحقول في الملف غير صالحة أو فارغة، سيتجاهل نظام التشغيل Android القواعد الديناميكية وسيعود الجهاز إلى القواعد المحدّدة بشكل ثابت في ملف بيان التطبيق.

لا يمكن للقواعد الديناميكية تحديد سوى القواعد التي تنطبق ضمن نطاق النطاقات التي تحدّدها في ملف بيان تطبيقك. يُرجى مراجعة القسم أدناه.

تعريف القواعد الديناميكية

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

• مطابقة المسار
  • المفتاح: "/"
  • القيمة: سلسلة واحدة، تعبير مطابق لمسار عنوان URL
• مطابقة الأجزاء
  • المفتاح: "#"
  • القيمة: سلسلة واحدة، تعبير مطابق لجزء عنوان URL
• مطابقة مَعلمات طلب البحث
  • المفتاح: "؟"
  • القيمة: قاموس لمطابقة أزواج المفتاح/القيمة في مَعلمات طلب البحث لعنوان URL.
  • على سبيل المثال، سيتطابق القاموس {"?", {"dl": "*", "in_app":"true"} مع سلسلة الطلب "?in_app=true&dl=abc".
  • ليس من الضروري أن يتطابق ترتيب أزواج المفاتيح/القيم في القاموس مع ترتيب الأزواج في سلسلة طلب البحث. بالإضافة إلى ذلك، لا يجب أن يتطابق القاموس مع جميع أزواج المفتاح/القيمة في سلسلة طلب البحث، ولكن يجب العثور على تطابق لكل إدخال في القاموس.
  • على سبيل المثال، سيتطابق القاموس أيضًا مع سلسلة طلب البحث "?lang=en&in_app=true&tz=pst&dl=abc"، ولكن لن يتطابق مع سلسلة طلب البحث "?lang=en&tz=pst&dl=abc".
• مستبعَدة
  • المفتاح: "exclude"
  • القيمة: قيمة اختيارية صحيحة/خاطئة لكل قاعدة محدّدة في dynamic_app_link_components (راجِع المثال).

يمكنك استخدام هذه الرموز الخاصة في أدوات مطابقة الأنماط:

• تتطابق "*" مع صفر أو أكثر من الأحرف إلى أن يتم العثور على الحرف الذي يلي حرف البدل في النمط في السلسلة المطابقة
• تتطابق "؟" مع أي حرف مفرد
• يتطابق "?*" مع حرف واحد أو أكثر

لا توجد قيود أخرى على الأحرف في القيم.

ترتيب القواعد الديناميكية

يُعدّ ترتيب تحديد القواعد مهمًا. يقيّم نظام التشغيل Android كل قاعدة بالترتيب إلى أن يعثر على تطابق.

يوضّح المثال التالي كيف يمكن أن يؤثر الترتيب في طريقة التعامل مع البيانات. تتطابق القاعدة الأولى مع جميع المسارات ("*") ولكنها تستبعد التطابقات (exclude: true)، ما يعني أنّها تستبعد جميع عناوين URL من فتح التطبيق. في هذه الحالة، لن يتم تقييم القاعدة الثانية التي تسمح بالمسار "/path1" أبدًا.

dynamic_app_link_components: [
  {​"/": "*", exclude: true},
  {​"/": "/path1"}
]

في المثال التالي، تم تحديد القاعدة "/path1" أولاً، لذا سيتم تقييمها أولاً وسيتم فتح التطبيق لعنوان URL مطابق لـ "/path1". سيتم تقييم القاعدة الثانية، التي تستبعد جميع عناوين URL من فتح التطبيق، في الخطوة الثانية، ولكن فقط إذا لم تتطابق القاعدة الأولى.

dynamic_app_link_components: [
  {​"/": "/path1"},
  {​"/": "*", exclude: true}
]

تحديد نطاق قواعدك الديناميكية بشكلٍ سليم

عند تحديد قواعد من جهة الخادم لاستخدامها مع "روابط التطبيقات الديناميكية" في نظام التشغيل Android 15 والإصدارات الأحدث، من المهم تحديد نطاقها بشكل مناسب لكي تعمل مع فلاتر الأهداف الثابتة المحدّدة في بيان التطبيق وتكمّلها.

لا يمكن للقواعد الديناميكية المحدّدة في ملف assetlinks.json سوى تحديد قواعد للمضيفين الذين تحدّدهم في ملف AndroidManifest.xml الخاص بتطبيقك. لا يمكن للقواعد الديناميكية توسيع نطاق قواعد عناوين URL التي تحدّدها بشكل ثابت في بيان تطبيقك.

لهذا السبب، ننصحك باتّباع هذا النهج في جميع قواعدك الديناميكية والثابتة:

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

باستخدام هذا الإعداد المثالي، ستتمكّن من إضافة مسارات جديدة لروابط التطبيق بشكل ديناميكي في ملف assetlinks.json حسب الحاجة، مع العلم أنّها ستندرج ضمن النطاق الواسع الذي حدّدته في بيان التطبيق.

تحديد dynamic_app_link_components مرة واحدة فقط

للتعامل مع القواعد بشكلٍ سليم، عليك تعريف عنصر dynamic_app_link_components واحد فقط في جميع العبارات الخاصة بموقع إلكتروني وعلاقة وتطبيق معيّن.

• ابحث عن عبارات متعدّدة للموقع الإلكتروني والعلاقة والتطبيق نفسه، والتي تعرّف عنصر dynamic_app_link_components.
• ابحث عن عناصر dynamic_app_link_components متعدّدة تم تعريفها في عبارة واحدة.

في حالات مثل هذه، لا يضمن نظام التشغيل Android تحديد إعدادات القواعد الديناميكية التي سيتم استخدامها.

توافُق القواعد الديناميكية مع عمليات ضبط "روابط التطبيق" السابقة

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

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

نشر ملف JSON لإثبات الملكية

يجب نشر ملف إثبات صحة JSON في الموقع التالي:

https://domain.name/.well-known/assetlinks.json

يُرجى التأكّد مما يلي:

• يتم عرض ملف assetlinks.json باستخدام نوع المحتوى application/json.
• يجب أن يكون ملف assetlinks.json قابلاً للوصول إليه عبر اتصال HTTPS، بغض النظر عمّا إذا كانت فلاتر الأهداف في تطبيقك تحدّد HTTPS كمخطط للبيانات.
• يجب أن تتوفّر إمكانية الوصول إلى ملف assetlinks.json بدون أي عمليات إعادة توجيه (لا عمليات إعادة توجيه 301 أو 302).
• إذا كانت روابط تطبيقك تتيح استخدام نطاقات مضيفة متعددة، عليك نشر ملف assetlinks.json على كل نطاق. اطّلِع على إتاحة ربط التطبيقات بمضيفين متعددين.
• يجب عدم نشر تطبيقك مع عناوين URL تجريبية في ملف البيان قد لا تكون متاحة للجميع (مثل أي عناوين لا يمكن الوصول إليها إلا من خلال شبكة VPN). في مثل هذه الحالات، يمكنك ضبط تنويعات الإصدار لإنشاء ملف بيان مختلف لإصدارات التطبيق المخصّصة للمطوّرين.

اطّلِع على الأدلة ذات الصلة التالية:

• إنشاء قائمة كشوفات
• "مساعِد روابط التطبيقات" في "استوديو Android"
• أدوات المطوّرين لـ "روابط التطبيق"