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

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

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

تتيح رموز Private State Tokens (المعروفة سابقًا باسم Trust Tokens) نقل الثقة في صحة هوية المستخدم من سياق إلى آخر، مع مساعدة المواقع الإلكترونية في مكافحة الاحتيال والتمييز بين برامج التتبُّع والمستخدمين الحقيقيين، وذلك بدون تتبُّع غير نشط.

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

طريقة عمل رموز Private State Tokens

العلاقة الأساسية التي يجب فهمها في نظام الدفع مقابل الخدمة هي العلاقة بين الجهات التي تصدر التذاكر والجهات التي تقبلها. يمكن أن يكون الجهات المصدرة والجهات المستردة داخل الشركة نفسها.

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

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

هل واجهة برمجة التطبيقات Private State Tokens API مناسبة لي؟

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

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

يتم تنفيذ PST على ثلاث مراحل:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

قبل استخدام PST، ننصحك بإعداد العرض التوضيحي.

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

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

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

• تأكَّد من إيقاف جميع نُسخ 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، والذي يستخدم مكتبة BoringSSL لإدارة الرموز المميّزة. يمكنك العثور على مثال على رمز الجهة المصدرة والمزيد من المعلومات حول التثبيت على GitHub

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

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

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

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

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

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

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

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

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

خوادم الاسترداد

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

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

المتطلبات الفنية لخوادم استرداد القيمة

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

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

إرسال طلب إلى خادم الاسترداد

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

    // 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>]
      }
    });

نموذج الرمز

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

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

عملية النشر في العالم الواقعي

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

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

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

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

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

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

كيفية التحكّم في ميزات Privacy Sandbox باستخدام "سياسة الأذونات" أو مزيد من المعلومات عن "سياسة الأذونات"

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

يمكنك فحص 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).

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

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

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

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

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