بنية قائمة كشف الحساب

قائمة البيانات هي ملف أو مقتطف بترميز JSON في موقع معروف.

موقع قائمة الكشوفات

اطّلِع على إنشاء قائمة بيانات لمعرفة مكان تخزين هذه القائمة.

البنية

تتألف قائمة البيانات أو المقتطف من مصفوفة JSON تضم بيانًا واحدًا أو أكثر من بيانات المواقع الإلكترونية أو التطبيقات كعناصر JSON. يمكن أن تكون هذه العبارات بأي ترتيب. في ما يلي بناء الجملة العام:

[
  {
    "relation": ["relation_string"],
    "target": {target_object}
  } , ...
]

relation

مصفوفة تتضمّن سلسلة واحدة أو أكثر من السلاسل التي تصف العلاقة التي يتم الإعلان عنها بشأن الهدف. اطّلِع على قائمة سلاسل العلاقات المحدّدة. مثال: delegate_permission/common.handle_all_urls

الاستهداف

تمثّل هذه السمة مادة العرض المستهدَفة التي تنطبق عليها هذه العبارة. أنواع الاستهداف المتاحة:

• استهداف الموقع الإلكتروني

  "target": {
    "namespace": "web",
    "site": "site_root_url"
  }

  مساحة الاسم

  يجب أن تكون web للمواقع الإلكترونية.

  الموقع

  معرّف الموارد المنتظم (URI) للموقع الإلكتروني الذي يستهدفه البيان، بالتنسيق http[s]://<hostname>[:<port>]، حيث يكون <hostname> مؤهلاً بالكامل، ويجب حذف <port> عند استخدام المنفذ 80 لبروتوكول HTTP أو المنفذ 443 لبروتوكول HTTPS. لا يمكن أن يكون هدف الموقع الإلكتروني سوى نطاق جذر، ولا يمكنك الاقتصار على دليل فرعي معيّن، بل ستتطابق جميع الأدلة الفرعية ضمن هذا الجذر. يجب عدم اعتبار النطاقات الفرعية متطابقة، أي إذا كان ملف البيان مستضافًا على www.example.com، يجب عدم اعتبار www.puppies.example.com مطابقًا. للاطّلاع على القواعد والأمثلة حول مطابقة استهداف المواقع الإلكترونية، يُرجى مراجعة مستندات الاستهداف. مثال: http://www.example.com

• استهداف تطبيقات Android

  "target": {
    "namespace": "android_app",
    "package_name": "fully_qualified_package_name",
    "sha256_cert_fingerprints": ["cert_fingerprint"]
  }

  مساحة الاسم

  يجب أن تكون القيمة android_app لتطبيقات Android.

  package_name

  اسم الحزمة المؤهّل بالكامل للتطبيق الذي ينطبق عليه هذا البيان. مثال: com.google.android.apps.maps

  sha256_cert_fingerprints

  الملف المرجعي لشهادة SHA256 بأحرف كبيرة الخاصة بالتطبيق الذي ينطبق عليه هذا البيان. يمكنك احتساب ذلك باستخدام openssl أو Java keytool كما هو موضّح هنا:

  • openssl x509 -in $CERTFILE -noout -fingerprint -sha256
  • keytool -printcert -file $CERTFILE | grep SHA256

  مثال: ["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"].

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

‫relation_extensions (اختيارية)

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

على سبيل المثال، قد يبدو relation_extensions للعلاقة delegate_permission/common.handle_all_urls على النحو التالي:

  {
    "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": {...}
    }
  }
  

تتيح واجهة برمجة التطبيقات DAL عرض relation_extensions في طلبات البيانات من واجهة برمجة التطبيقات عند ضبط المَعلمة return_relation_extensions=true في الطلب.

مثال على قائمة الكلمات الرئيسية

في ما يلي مثال على قائمة بيانات موقع إلكتروني تتضمّن بيانات حول المواقع الإلكترونية والتطبيقات: http://example.digitalassetlinks.org/.well-known/assetlinks.json

التوسّع ليشمل عشرات البيانات أو أكثر

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

في هذه الحالات، يمكن أن تكون عبارات التضمين مفيدة. باستخدام هذه الآلية، يمكنك إعداد مؤشرات من العديد من الجهات الرئيسية المختلفة إلى موقع مركزي واحد، يحدّد البيانات لجميع الجهات الرئيسية.

على سبيل المثال، يمكنك تحديد أنّ الموقع المركزي يجب أن يكون `https://example.com/includedstatements.json`. ويمكن ضبط هذا الملف ليتضمّن المحتوى نفسه الوارد في الأمثلة أعلاه.

لإعداد مؤشر من موقع إلكتروني إلى ملف التضمين، غيِّر `https://example.com/.well-known/assetlinks.json` إلى:

[{
  "include": "https://example.com/includedstatements.json"
}]

لإعداد مؤشر من تطبيق Android إلى ملف التضمين، غيِّر `res/values/strings.xml` إلى ما يلي:

<resources>
  ...
  <string name="asset_statements">
    [{
      \"include\": \"https://example.com/includedstatements.json\"
    }]
  </string>
</resources>

مزيد من المعلومات

يمكنك الاطّلاع على شرح أكثر تفصيلاً حول تنسيق قائمة البيانات والمفاهيم الأساسية في مستند المواصفات.