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

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

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

يوضّح هذا الدليل كيفية إعداد ملف assetlinks.json ونشره على موقعك الإلكتروني. إذا كنت تفضّل ذلك، يمكنك إنشاء ملف assetlinks.json من أداة Play Deep Links أو "مساعِد روابط التطبيقات" في "استوديو 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 بالتطبيق 1. تعرض القائمة الأولى ربط example.com بالتطبيق 1:

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 بالتطبيق 1. يختلف الموقع الإلكتروني الذي يتم فيه استضافة هذه الملفات فقط (‫.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"]
  }
}]

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

تتيح لك "روابط التطبيق الديناميكية" في Android 15 والإصدارات الأحدث استخدام قواعد مطابقة الروابط لصفحات معيّنة من جهة الخادم، والتي تعمل مع القواعد التي حدّدتها بشكل ثابت في بيان تطبيقك. يُستخدم ملف 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 حسب الحاجة، مع العلم أنّها ستناسب النطاق الواسع الذي ضبطته في بيان التطبيق.

الإعلان عن dynamic_app_link_components مرة واحدة فقط

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

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

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

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

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

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

نشر ملف التحقّق بتنسيق 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"
• أدوات المطوّرين لروابط التطبيقات