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

لاستخدام روابط التطبيقات، عليك إنشاء ملف روابط تنقّل إلى مواد عرض رقمية بتنسيق 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 الخاص بشهادة توقيع تطبيقك. يمكنك استخدام الأمر التالي لإنشاء بصمة الإصبع باستخدام أداة Java keytool:

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 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 35) أو الإصدارات الأحدث والتي تم تثبيت خدمات 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}
        ]
      }
    }
  }
]

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

• تضيف "روابط التطبيق الديناميكية" إضافة جديدة إلى علاقات روابط تنقل إلى مواد عرض رقمية تُسمى 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}
]

إذا لم يتم العثور على أي تطابقات في قائمة المكوّنات المحدّدة، لن يفتح عنوان URL التطبيق. في المثال التالي، لا يتطابق أي من المسارات مع "/path3"، لذا سيتعامل الجهاز مع هذا المسار على أنّه مستبعَد.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

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

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

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

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

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

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

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

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

التعريف بمكوّنات App Link الديناميكية مرة واحدة فقط

للتعامل مع القواعد بشكلٍ سليم، يجب تحديد عنصر 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 تجريبية في ملف البيان قد لا تكون متاحة للجميع (مثل أي عناوين URL لا يمكن الوصول إليها إلا من خلال شبكة VPN). في مثل هذه الحالات، يكون الحل البديل هو ضبط تنويعات الإصدارات لإنشاء ملف بيان مختلف لإصدارات التطوير.

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

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