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

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

بالنسبة إلى "روابط التطبيقات" الديناميكية في Android 15 والإصدارات الأحدث، يُعدّ ملف assetlinks.json أيضًا المكان الذي تحدّد فيه إعدادات القواعد الديناميكية، مثل مطابقة الأنماط للمسار والجزء ومَعلمات طلب البحث. ستسترد أجهزة Android التي تعمل بالإصدار 15 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 35) أو الإصدارات الأحدث والتي تم تثبيت خدمات 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"]
  }
}]

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

تتيح لك ميزة "روابط التطبيقات الديناميكية" في 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 متعددة تم تعريفها في عبارة واحدة

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

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

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

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

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

يجب نشر ملف JSON الخاص بالتحقّق في الموقع التالي:

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

تأكَّد مما يلي:

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

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