دليل مطوّري الرموز المميّزة للحالة الخاصة

في السابق، كانت ملفات تعريف الارتباط التابعة لجهات خارجية تُستخدَم لتخزين معلومات العميل ونقلها، مثل حالة تسجيل الدخول أو معلومات عن الجهاز الذي يستخدمه أو ما إذا كان معروفًا وموثوقًا به. على سبيل المثال، ما إذا كان العميل قد سجّل الدخول باستخدام خدمة الدخول المُوحَّد (SSO)، أو ما إذا كان العميل يمتلك نوعًا معيّنًا من الأجهزة المتوافقة، أو ما إذا كان العميل معروفًا وموثوقًا به. مع إيقاف استخدام ملفات تعريف الارتباط التابعة لجهات خارجية نهائيًا، يجب توفير وسائل أخرى لدعم العديد من حالات الاستخدام هذه.

توفّر "رموز الحالة الخاصة" طريقة لمشاركة المعلومات على الويب، ولكن بطريقة تحافظ على الخصوصية من خلال عناصر التحكّم في مقدار البيانات التي يمكن مشاركتها فعليًا.

تسمح "الرموز المميّزة للحالة الخاصة" (المعروفة سابقًا باسم "رموز الثقة") بنقل الثقة في هوية المستخدِم من سياق إلى آخر، مع مساعدة المواقع الإلكترونية في مكافحة الاحتيال وتمييز برامج التتبُّع عن الأشخاص الحقيقيين، بدون التتبُّع السلبي.

يوضّح هذا المستند التفاصيل الفنية لتنفيذ الرموز المميّزة الخاصة بالحالة (PST). للحصول على مخطّط أكثر تفصيلاً، يُرجى الاطّلاع على نظرة عامة على ملفات PST.

كيف تعمل الرموز المميّزة للحالة الخاصة؟

إنّ العلاقة الرئيسية التي يجب فهمها في PST هي بين الجهات المُصدِرة والجهات المُستحِقة. يمكن أن يكون كلّ من الجهات المُصدِرة والمُستلِمة من الشركة نفسها.

• المُصدرون: تتوفّر لهذه الكيانات بعض الإشارات عن المستخدم (مثل ما إذا كان هذا المستخدم بوتًا أم لا)، وتُدمج هذه الإشارات في رمز متغيّر يتم تخزينه على جهاز المستخدم (مزيد من التفاصيل في الأقسام التالية).
• المستخدمون الذين يطلبون تحصيل القيمة: قد لا تتوفّر لهذه الكيانات معلومات عن المستخدم، ولكنهم يحتاجون إلى معرفة معلومات عنه (على سبيل المثال، ما إذا كان هذا المستخدم بوتًا أم لا) ويطلبون تحصيل قيمة رمز مميّز من الجهة المُصدِرة لمعرفة مدى أمان هذا المستخدم.

يتطلّب كل تفاعل مع PST تعاونًا بين الجهات المُصدِرة والجهات المُستحِقة لمشاركة الإشارات على الويب. هذه الإشارات هي قيم تقريبية ليست مفصّلة بالقدر الكافي لتحديد هوية الأفراد.

هل الرموز المميّزة للحالة الخاصة مناسبة لي؟

يمكن أن تستفيد الشركات التي تتّخذ قرارات تتعلق بالثقة وتريد أن تكون هذه المعلومات متوفرة في جميع السياقات من جداول بيانات النقاط المهمة. لمزيد من المعلومات عن حالات الاستخدام المحتملة لملفات PST، اطّلِع على مستنداتنا حول حالات استخدام ملفات PST.

إصدار الرموز المميّزة وتحصيل قيمتها

يتم تنفيذ توقيت المحيط الهادئ على ثلاث مراحل:

1. إصدار الرموز المميّزة
2. تحصيل الرموز المميّزة
3. إعادة توجيه سجلّ تحصيل القيمة

في المرحلة الأولى، يتم إصدار الرموز المميّزة لمتصفّح (عادةً بعد إجراء نوع من التحقّق). في المرحلة الثانية، سيقدّم كيان آخر طلبًا لاسترداد الرمز المميّز الذي تم إصداره لقراءة القيمة في ذلك الرمز المميّز. في المرحلة النهائية، يتلقّى الطرف الذي يطالب بالقيمة سجلّ تحصيل قيمة الرمز المميّز (RR) بالقيمة التي كانت مضمّنة في الرمز المميّز. ويمكن للطرف الذي يطالب بالقيمة استخدام هذا السجلّ كشهادة إثبات ملكية هذا المستخدم لأغراض مختلفة.

تحديد استراتيجية الرموز المميّزة

لتحديد استراتيجية الرموز المميّزة، عليك فهم المفاهيم الرئيسية لبروتوكول PST (الرموز المميّزة وسجلّات تحصيل القيمة) والمتغيّرات والسلوكيات والقيود لكي تتمكّن من التفكير في استخدامها المحتمل في حالة الاستخدام.

الرموز وسجلّات تحصيل القيمة: ما هي العلاقة بينهما؟

يمكن لكل جهاز تخزين ما يصل إلى 500 رمز مميّز لكل موقع إلكتروني ومؤسسة إصدار من المستوى الأعلى. بالإضافة إلى ذلك، يحتوي كل رمز مميّز على بيانات وصفية تشير إلى المفتاح الذي استخدمه المُصدِر لإصداره. ويمكن استخدام هذه المعلومات لتحديد ما إذا كان سيتم تحصيل قيمة الرمز المميّز أم لا أثناء عملية تحصيل القيمة. يخزِّن المتصفّح بيانات PST داخليًا على جهاز المستخدم، ولا يمكن الوصول إليها إلا من خلال PST API.

عند تحصيل قيمة رمز مميَّز، يتم تخزين سجلّ تحصيل القيمة (RR) على الجهاز. وتعمل مساحة التخزين هذه كذاكرة تخزين مؤقت لعمليات تحصيل القيمة المستقبلية. يمكن استخدام علامتَين رمزيتين كل 48 ساعة كحد أقصى لكل جهاز وصفحة ومؤسسة إصدار. ستستخدم طلبات تحصيل القيمة الجديدة السجلّات الدائمة للنطاقات كلما أمكن ذلك، بدلاً من إرسال طلب إلى المُصدِر.

1. يتم إصدار رموز مميّزة جديدة (500 رمز بحد أقصى لكل جهة إصدار وموقع إلكتروني وجهاز).
2. يتم تخزين جميع الرموز المميّزة في متجر الرموز المميّزة على الجهاز (على غرار متجر ملفات تعريف الارتباط).
3. إذا لم يتم العثور على سجلّ موارد نشط، يمكن إنشاء سجلّات موارد جديدة بعد إصدارها (اثنان بحد أقصى كل 48 ساعة).
4. تُعتبر سجلات RR نشطة حتى تاريخ انتهاء الصلاحية، وسيتم استخدامها كملف cach محلي.
5. ستتم معالجة طلبات تحصيل القيمة الجديدة في ذاكرة التخزين المؤقت المحلية (لن يتم إنشاء أي سجلّات RR جديدة).

بعد تحديد حالة الاستخدام، عليك تحديد مدة صلاحية الرمز المميّز للردّ بعناية، لأنّه سيحدّد عدد المرات التي ستتمكّن فيها من استخدامه في حالتك.

تأكَّد من فهم السلوكيات والمتغيّرات المهمة التالية قبل تحديد strategiتك:

أمثلة على السيناريوهات

السيناريو 1: مدة صلاحية الرمز الترويجي أقل من 24 ساعة (t=t) ويتم تحصيل قيمة الرمز الترويجي متعدد المرات خلال فترة 48 ساعة.

السيناريو 2: مدة صلاحية الرمز الترويجي هي 24 ساعة ويتم تحصيل قيمة الرمز الترويجي متعدد المرات خلال فترة 48 ساعة.

السيناريو 3: مدة صلاحية الرمز المميّز للمكافأة هي 48 ساعة ويتم تحصيل القيمة متعدد المرات خلال فترة 48 ساعة.

تشغيل العرض الترويجي

قبل استخدام PST، ننصحك بالإعداد باستخدام الإصدار التجريبي أولاً. لتجربة الإصدار التجريبي من PST، عليك تشغيل Chrome مع إضافة علامات لتفعيل التزامات مُصدر الإصدار التجريبي المفتاحية (اتّبِع التعليمات المتوفّرة في صفحة الإصدار التجريبي).

من خلال تشغيل هذا العرض التجريبي، يستخدم المتصفّح ملفَي برمجة تطبيقات لخدمة إصدار الرموز المميّزة واستخدامها لتوفير الرموز المميّزة واستخدامها.

اعتبارات فنية

سيعمل العرض الترويجي على أفضل نحو إذا نفّذت الخطوات التالية:

• تأكَّد من إيقاف جميع نُسخ Chrome قبل تشغيل Chrome باستخدام العلامات.
• إذا كنت تستخدم جهاز كمبيوتر يعمل بنظام التشغيل Windows، يمكنك الاطّلاع على هذا الدليل الذي يشرح كيفية تمرير المَعلمات إلى الملف الثنائي القابل للتنفيذ من Chrome.
• افتح "أدوات مطوّري البرامج في Chrome" ضمن التطبيقات > مساحة التخزين > الحالة الخاصة الرموز المميّزة أثناء استخدام التطبيق التجريبي للاطّلاع على الرموز المميّزة التي أصدرَها/استردّها مُصدر التطبيق التجريبي.

الإعداد لاستخدام الميزة

الانضمام إلى الجهات المُصدِرة

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

لتقديم طلب ليصبح جهة إصدار، على مشغّل الموقع الإلكتروني لجهة الإصدار فتح مشكلة جديدة في مستودع GitHub باستخدام نموذج "جهة إصدار PST جديدة". اتّبِع الإرشادات الواردة في المستودع لتعبئة المشكلة. بعد التحقّق من نقطة نهاية، سيتم دمجها في هذا المستودع وستبدأ البنية الأساسية من جهة خادم Chrome في جلب هذه المفاتيح.

خوادم الجهات المُصدِرة

الجهات المُصدِّرة وجهات تحصيل القيمة هما الجهات الرئيسية في PST، وتعدّ الخوادم والرموز المميّزة هما الأدوات الرئيسية في PST. على الرغم من أنّنا قد قدّمنا بعض التفاصيل حول الرموز المميّزة في مستندات GitHub، أردنا تقديم المزيد من التفاصيل حول خوادم PST. للإعداد كمُصدِر لشهادات PST، عليك أولاً إعداد خادم إصدار.

نشر بيئتك: خوادم المُصدرين

لتنفيذ خادم مُصدِّر الرموز المميّزة، عليك إنشاء تطبيق خاص بك على جانب الخادم يعرِض نقاط نهاية HTTP.

يتألّف مكوّن المُصدِر من وحدتَين رئيسيتين: (1) خادم المُصدِر و (2) مُصدِر الرمز المميّز.

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

1. خادم المُصدر: في مثال التنفيذ، يكون خادم المُصدر هو خادم Node.js الذي يستخدم إطار عمل Express لاستضافة نقاط نهاية HTTP الخاصة بالمُصدر. يمكنك الاطّلاع على نموذج الرمز على GitHub.

2. جهة إصدار الرمز المميّز: لا يتطلّب المكوّن التشفيري الخاص بجهة الإصدار أي لغة معيّنة، ولكن بسبب متطلبات الأداء لهذا المكوّن، نقدّم مثالاً على تنفيذ لغة C يستخدم مكتبة Boring SSL لإدارة الرموز المميّزة. يمكنك العثور على مثال على رمز المُصدر والمزيد من المعلومات عن عملية التثبيت على GitHub.

3. المفاتيح: يستخدم مكوّن جهة إصدار الرموز المميّزة مفاتيح مخصّصة لتشفير الرموز المميّزة. يجب حماية هذه المفاتيح وتخزينها في مساحة تخزين آمنة.

المتطلبات الفنية لخوادم الجهات المُصدِرة

وفقًا للبروتوكول، عليك تنفيذ نقطتَي نهاية HTTP على الأقل في خادم المُصدر:

• التزام المفتاح (على سبيل المثال، /.well-known/private-state-token/key-commitment): هي نقطة النهاية التي ستتوفّر فيها تفاصيل المفتاح العام للتشفير للمتصفّحات لتأكيد أنّ خادمك شرعي.
  • مثال على الرمز
• إصدار الرمز المميّز (على سبيل المثال، /.well-known/private-state-token/issuance): نقطة نهاية إصدار الرمز المميّز التي ستتم فيها معالجة جميع طلبات الرموز المميّزة. ستكون نقطة النهاية هذه هي نقطة دمج مكوّن جهة إصدار الرمز المميّز.
  • مثال على الرمز

كما ذكرنا سابقًا، بسبب العدد الكبير المتوقع للزيارات التي قد يتعامل معها هذا الخادم، ننصح بنشره باستخدام بنية أساسية قابلة للتوسّع (على سبيل المثال، في بيئة السحابة الإلكترونية) لتتمكّن من تعديل الخلفيّة استنادًا إلى الطلب المتغيّر.

إرسال طلب إلى خادم جهة الإصدار

نفِّذ طلب جلب موقع إلكتروني إلى حِزمة إصدار الرموز من أجل إصدار رموًز جديدة.

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

الاطّلاع على مثال على الرمز

خوادم Redeemer

ستحتاج إلى تنفيذ خدمة تحصيل قيمة الرمز المميّز من خلال إنشاء تطبيق من جهة الخادم. سيتيح لك ذلك قراءة الرموز المميّزة التي يُرسِلها مُصدِر البطاقة. توضّح الخطوات التالية كيفية تحصيل الرموز المميّزة وكيفية قراءة سجلّات تحصيل الرموز المميّزة المرتبطة بهذه الرموز.

يمكنك اختيار تشغيل جهة الإصدار وجهة تحصيل القيمة في الخادم نفسه (أو مجموعة من الخوادم).

المتطلبات الفنية لخوادم تحصيل القيمة

وفقًا للبروتوكول، عليك تنفيذ نقطتَي نهاية HTTP على الأقل ل خادم تحصيل القيمة:

• ‫/.well-known/private-state-token/redemption: نقطة النهاية التي سيتم من خلالها التعامل مع كل عمليات redeemed الاستفادة من الرموز المميّزة ستكون نقطة النهاية هذه هي المكان الذي سيتم فيه دمج عنصر تحصيل القيمة للرمز المميّز
  .
  • مثال على الرمز

إرسال طلب إلى خادم تحصيل القيمة

للاستفادة من الرموز المميّزة، عليك تنفيذ طلب جلب موقع إلكتروني ل تجميع الاستفادة من الرموز المميّزة من أجل الاستفادة من الرموز المميّزة التي تم إصدارها من قبل.

    // redemption request
    await fetch("/.well-known/private-state-token/redemption", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-redemption",
        refreshPolicy: "none"
      }
    });

اطّلِع على عيّنة الرمز البرمجي.

بعد تحصيل رمز مميّز، يمكنك إرسال سجلّ تحصيل القيمة (RR) من خلال تنفيذ طلب استرجاع آخر:

    // attach redemption records from the issuers to the request
    await fetch("<DESTINATION_RESOURCE>", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "send-redemption-record",
        issuers: [<ISSUER_DOMAIN>]
      }
    });

اطّلِع على عيّنة الرمز البرمجي.

نشر عملية التنفيذ

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

عمليات النشر في العالم الحقيقي

ننصحك باختيار المواقع الإلكترونية المستهدَفة التي تشكّل جزءًا من حالة الاستخدام الخاصة بك:

• عدد قليل من الزيارات الشهرية (أقل من مليون زيارة في الشهر تقريبًا): يجب أولاً نشر واجهة برمجة التطبيقات على شريحة جمهور صغيرة.
• أنت تملكها وتتحكّم فيها: يمكنك إيقاف عملية التنفيذ بشكل سريع إذا لزم الأمر بدون الحصول على الموافقات المعقدة.
• لا يزيد عن جهة إصدار واحدة: للحد من عدد الرموز المميّزة من أجل تبسيط الاختبار.
• لا يُسمح بأكثر من شخصَين للاستفادة من العرض: عليك تبسيط عملية تحديد المشاكل وحلّها في حال حدوثها.

سياسة الأذونات

لكي تعمل بشكل صحيح، يجب أن تكون PST API متاحة للصفحة ذات المستوى الأعلى وأي موارد فرعية تستخدم واجهة برمجة التطبيقات.

يتم التحكّم في عملية طلب الرمز المميّز من خلال التوجيه private-state-token-issuance. تخضع العمليتان token-redemption وsend-redemption-record للتوجيه private-state-token-redemption. في الإصدار 132 من Chrome والإصدارات الأحدث، يتم ضبط القائمة المسموح بها لهذه التعليمات على * (جميع المصادر) تلقائيًا. وهذا يعني أنّ الميزة متاحة للصفحة ذات المستوى الأعلى، وإطارات iframe من المصدر نفسه، وإطارات iframe من مصادر متعددة بدون تفويض صريح.

يمكنك إيقاف إصدار أو تحصيل رمز PST لصفحات معيّنة على موقعك الإلكتروني عن طريق تضمين private-state-token-issuance=() وprivate-state-token-redemption=() في عنوان Permissions-Policy لكل صفحة.

يمكنك أيضًا استخدام العنوان Permissions-Policy للتحكّم في إمكانية وصول الجهات الخارجية إلى PST. استخدِم self وأي مصادر تريد السماح لها بالوصول إلى واجهة برمجة التطبيقات كمَعلمات لقائمة مصادر العناوين. على سبيل المثال، لإيقاف استخدام المنطقة الزمنية PST نهائيًا في جميع سياقات التصفّح باستثناء مصدرك وhttps://example.com، اضبط عناوين استجابة HTTP التالية:

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

لتفعيل واجهة برمجة التطبيقات لجميع الموارد من مصادر مختلفة، اضبط قائمة المصادر على *.

تعرَّف على كيفية التحكّم في ميزات "مبادرة حماية الخصوصية" باستخدام "سياسة الأذونات" أو التعمّق في فهم سياسة الأذونات.

تحديد المشاكل وحلّها

يمكنك فحص ملفات PST من علامتَي التبويب "الشبكة" و"التطبيق" في "أدوات مطوّري البرامج في Chrome".

في علامة التبويب "الشبكة":

في علامة التبويب "التطبيق":

يمكنك الاطّلاع على مزيد من المعلومات عن دمج أدوات المطوّرين.

أفضل الممارسات المتعلّقة بالعملاء

إذا كانت وظائف موقعك الإلكتروني المهمة تعتمد على جهات إصدار معيّنة للرموز المميّزة، امنح الأولوية لها. يُرجى الاتصال برقم ‎hasPrivateToken(issuer) لموفّري بطاقات الائتمان المفضّلين هؤلاء قبل تحميل أي نصوص برمجية أخرى. هذا أمر مهم لمنع حالات تعذُّر تحصيل القيمة المحتمَلة.

لا يمكن أن يزيد عدد الجهات المُصدِرة لكل مستوى أعلى من اثنين، وقد تحاول النصوص البرمجية التابعة لجهات خارجية أيضًا استدعاء hasPrivateToken(issuer) لمنح الأولوية للجهات المُصدِرة المفضّلة لديها. لذا، عليك تأمين الجهات المُصدِرة الأساسية مُسبقًا للتأكّد من أنّ موقعك الإلكتروني يعمل على النحو المتوقّع.

  // Prioritize your critical token issuer.
  document.hasPrivateToken('https://critical-issuer.example')
    .then(hasToken => {
      if (hasToken) {
        // Use the token or perform actions based on its availability.
      } else {
        // Handle the case where the token is not available.
      }
    });

  // Load third-party scripts or secure another token issuer (up to two in total).

أفضل الممارسات المتعلقة بالخادم وتحديد المشاكل وحلّها

لكي يعمل خادم المُصدِر والمُستردّ بشكلٍ فعّال، ننصحك باتّباع أفضل الممارسات التالية لضمان عدم مواجهة أي تحديات تتعلّق بالوصول أو الأمان أو التسجيل أو عدد الزيارات في PST.

• يجب أن تطبّق نقاط النهاية نظام تشفير قويًا باستخدام بروتوكول أمان طبقة النقل (TLS) 1.3 أو 1.2.
• يجب أن تكون البنية الأساسية جاهزة للتعامل مع أعداد الزيارات المتغيرة (بما في ذلك الارتفاعات المفاجئة).
• تأكَّد من حماية مفاتيحك وأمانها، بما يتوافق مع سياسة التحكّم في الوصول واستراتيجية إدارة المفاتيح وخطط استمرارية الأعمال.
• أضِف مقاييس المراقبة إلى حِزمة التطبيقات للتأكّد من توفُّر بيانات المراقبة اللازمة لفهم الاستخدام والمشاكل المتعلّقة بالأداء والاختناقات بعد الانتقال إلى مرحلة الإنتاج.

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

1. راجِع مستندات المطوّرين:
   1. ابدأ بقراءة نظرة عامة لتكون على دراية بتنسيق PST وإمكانياته.
   2. شاهِد الفيديو التقديمي لبرنامج PST.
   3. جرِّب الإصدار التجريبي من PST.
   4. يمكنك أيضًا الاطّلاع على الشرح المتعلّق بواجهة برمجة التطبيقات للتعرّف على المزيد من التفاصيل حولها.
   5. يمكنك الاطّلاع على مزيد من المعلومات عن المواصفات الحالية لواجهة برمجة التطبيقات.
2. يمكنك المساهمة في المحادثة من خلال GitHub المشاكل أو W3C المكالمات.
3. لفهم أيّ من المصطلحات بشكل أفضل، راجِع مسرد "مبادرة حماية الخصوصية".
4. لمزيد من المعلومات عن مفاهيم Chrome، مثل "مرحلة تقييم وتجربة" أو "ميزات Chrome الاختبارية"، راجِع الفيديوهات والمقالات القصيرة المتوفّرة من goo.gle/cc.