تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

دليل المطوِّر في FLEDGE API

المستخدمون المعنيّون بهذه المقالة

تشكّل هذه المشاركة مرجعًا فنيًا للتكرار الحالي لواجهة برمجة التطبيقات Protected Audience API التجريبية.

Protected Audience API هي نظرة عامة أقلّ تقنية على الاقتراح، وتحتوي أيضًا على مسرد مصطلحات.
يقدّم العرض التوضيحي للجمهور المحمي جولة تفصيلية حول عملية نشر FLEDGE الأساسية.
يوضّح الفيديو التوضيحي للجمهور المحمي طريقة عمل الرمز التجريبي، كما يوضّح كيفية استخدام "أدوات مطوّري البرامج في Chrome" لتصحيح الأخطاء المتعلقة بالجمهور المحمي.

ما هو المقصود بالجمهور المحمي؟

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

Protected Audience هي أوّل تجربة يتم تنفيذها في Chromium ضمن مجموعة المقترحات TURTLEDOVE.

يقدم المخطّط أدناه نظرة عامة على دورة حياة FLEDGE:

صورة توضيحية تقدّم نظرة عامة على كل مرحلة من مراحل دورة حياة FLEDGE — مراحل نشاط FLEDGE.

كيف يمكنني تجربة ميزة Protected Audience؟

عرض توضيحي للجمهور المحمي

تتوفّر جولة تفصيلية حول عملية نشر "الجمهور المحمي" الأساسية على المواقع الإلكترونية للمعلِنين والناشرين على الرابط Protect-audience-demo.web.app.

يوضِّح الفيديو التوضيحي طريقة عمل الرمز التجريبي وكيفية استخدام "أدوات مطوري البرامج في Chrome" لتصحيح الأخطاء المتعلقة بالجمهور المحمي.

المشاركة في مرحلة التجربة والتقييم في "جمهور محمي"

تم توفير تجربة المصدر ذات الصلة بـ "مبادرة حماية الخصوصية" و"القياس" في الإصدار التجريبي 101.0.4951.26 والإصدارات الأحدث من Chrome على أجهزة الكمبيوتر المكتبي لواجهات برمجة التطبيقات Protected Audience وTopics وAttribution Reporting.

للمشاركة في البرنامج، يمكنك التسجيل للحصول على رمز مميّز لمرحلة التجربة والتقييم.

بعد التسجيل بنجاح في الفترة التجريبية، يمكنك تجربة Protected Audience JavaScript API على الصفحات التي توفّر رمزًا مميّزًا صالحًا للنسخة التجريبية: على سبيل المثال، يمكنك أن تطلب من المتصفّح الانضمام إلى مجموعة واحدة أو أكثر من مجموعات الاهتمامات، ثم إجراء مزاد إعلانات لاختيار إعلان وعرضه.

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

قدِّم رمزًا مميّزًا لفترة تجريبية لكل صفحة تريد تشغيل رمز Protected Audience API عليها:

كعلامة وصفية في <head>:

<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
كعنوان HTTP:

Origin-Trial: TOKEN_GOES_HERE

من خلال توفير رمز مميّز بشكل آلي:

const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

سيحتاج إطار iframe الذي يتم تشغيله برمز "الجمهور المحمي"، مثل طلب navigator.joinAdInterestGroup() من مالك مجموعة الاهتمامات، إلى توفير رمز مميّز يتطابق مع مصدره.

توفّر التفاصيل المقترَحة حول التجربة الأصلية للجمهور المحمي الأول مزيدًا من التفاصيل عن أهداف الفترة التجريبية الأولى وتوضّح الميزات المتاحة.

الاختبار باستخدام علامة `chrome://flags` أو علامات الميزات

يمكنك اختبار Protected Audience لمستخدم واحد في الإصدار التجريبي من Chrome 101.0.4951.26 والإصدارات الأحدث على أجهزة الكمبيوتر المكتبي: * من خلال تفعيل سياسة chrome://flags/#privacy-sandbox-ads-apis. * من خلال إعداد علامات من سطر الأوامر.

عرض الإعلانات في إطارات iframe أو إطارات مضمّنة

يمكن عرض الإعلانات في علامة <iframe> أو <fencedframe>، استنادًا إلى العلامات التي تم ضبطها.

لاستخدام <fencedframe> لعرض الإعلانات، اتّبِع الخطوات التالية:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

لاستخدام <iframe> لعرض الإعلانات، اتّبِع الخطوات التالية:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

ضمِّن العلامة BiddingAndScoringDebugReportingAPI لتفعيل الطرق المؤقتة لإعداد تقارير الخسارة/الفوز وتصحيح الأخطاء.

مقالة تشغيل Chromium باستخدام علامات لشرح كيفية ضبط العلامات عند تشغيل Chrome والمتصفحات الأخرى المستندة إلى Chromium من سطر الأوامر. تتوفّر القائمة الكاملة لعلامات "الجمهور المحمي" من خلال أداة Chromium Code Search.

ما الميزات المتوافقة في أحدث إصدار من Chrome؟

تم توفير ميزة Protected Audience خلف علامات الميزات في Chromium كتجربة أولى لاختبار الميزات التالية لاقتراح "الجمهور المحمي":

مجموعات الاهتمامات: يخزّنها المتصفّح مع البيانات الوصفية المرتبطة بها لإعداد عروض أسعار الإعلانات وعرضها.
عروض الأسعار على الجهاز فقط حسب المشترين (نظام وسيط عرض الطلب أو المعلِن): استنادًا إلى مجموعات الاهتمامات والإشارات المخزَّنة من البائع.
اختيار البائع للإعلانات على الجهاز فقط (SSP أو الناشر): استنادًا إلى عروض أسعار المزادات والبيانات الوصفية من المشترين
عرض الإعلانات في نسخة مريحة مؤقتة من الإطارات Fenced Frames: مع السماح بالوصول إلى الشبكة وتسجيلها لعرض الإعلانات

يقدّم شرح واجهة برمجة التطبيقات مزيدًا من التفاصيل حول دعم الميزات والقيود.

أذونات مجموعة الاهتمامات

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

خدمة المفتاح/القيمة

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

يتوفّر الآن رمز خدمة "مفتاح/قيمة الجمهور المحمي" في مستودع GitHub ضمن "مبادرة حماية الخصوصية". ويمكن لمطوِّري برامج Android وChrome استخدام هذه الخدمة. يمكنك مراجعة مشاركة مدونة الإعلان لمعرفة معلومات عن تحديث الحالة. اطّلِع على مزيد من المعلومات عن خدمة "مفتاح/قيمة الجمهور المحمي" من خلال شرح واجهة برمجة التطبيقات وشرح نموذج الثقة.

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

لضمان توفير وقت كافٍ للاختبار في المنظومة المتكاملة، لا نتوقّع أن نطلب استخدام خدمات المفتاح/القيمة المفتوحة المصدر أو واجهات التنفيذ الموثوقة (TEE) إلا بعد وقت محدّد من إيقاف ملفات تعريف الارتباط التابعة لجهات خارجية. وسنرسل إشعارًا مهمًا للمطوّرين لبدء عملية الاختبار والاعتماد قبل تنفيذ هذا الانتقال.

اكتشاف دعم الميزات

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

'joinAdInterestGroup' in navigator &&
  document.featurePolicy.allowsFeature('join-ad-interest-group') &&
  document.featurePolicy.allowsFeature('run-ad-auction') ?
  console.log('navigator.joinAdInterestGroup() is supported on this page') :
  console.log('navigator.joinAdInterestGroup() is not supported on this page');

كيف يمكنني إيقاف ميزة Protected Audience؟

يمكنك حظر الوصول إلى Protected Audience API إمّا كمالك للموقع الإلكتروني أو كمستخدم فردي.

كيف يمكن للمواقع الإلكترونية التحكّم في إمكانية الوصول؟

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

هناك سياستان لأذونات الجمهور المحمي يمكن ضبطهما بشكل مستقل: * يعمل "join-ad-interest-group" على تفعيل/إيقاف الوظائف لإضافة متصفِّح إلى مجموعات الاهتمامات. * يعمل "run-ad-auction" على تفعيل/إيقاف الوظائف لتنفيذ مزاد على الجهاز فقط.

يمكن إيقاف الوصول إلى Protected Audience API بالكامل في سياقات الطرف الأول من خلال تحديد سياسة الأذونات التالية في عنوان استجابة HTTP:

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

يمكنك إيقاف استخدام واجهات برمجة التطبيقات في إطار iframe من خلال إضافة السمة allow التالية إلى أحد عناصر iframe:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

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

إيقاف المستخدم

يمكن للمستخدم حظر الوصول إلى Protected Audience API وميزات "مبادرة حماية الخصوصية" الأخرى باستخدام أي من الآليات التالية:

إيقاف الإصدارات التجريبية من "مبادرة حماية الخصوصية" في إعدادات Chrome: الإعدادات > الأمان والخصوصية > مبادرة حماية الخصوصية. يمكن أيضًا الوصول إلى هذه المعلومات على الرابط chrome://settings/adPrivacy.
إيقاف ملفات تعريف الارتباط التابعة لجهات خارجية في إعدادات Chrome: الإعدادات > الأمان والخصوصية.
اضبط ملفات تعريف الارتباط وبيانات الموقع الإلكتروني الأخرى على "حظر ملفات تعريف الارتباط التابعة لجهات خارجية" أو "حظر كل ملفات تعريف الارتباط" من chrome://settings/cookies.
استخدام "وضع التصفّح المتخفي"

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

تصحيح أخطاء نماذج "الجمهور المحمي"

من خلال الإصدار 98.0.4718.0 من Chrome Canary، يمكن تصحيح أخطاء نماذج "الجمهور المحمي" ضمن "أدوات مطوري البرامج في Chrome".

تتمثّل الخطوة الأولى في تحديد نقاط التوقف من خلال فئة جديدة في لوحة نقاط إيقاف أداة معالجة الحدث في لوحة المصادر.

لقطة شاشة تُظهر في "أدوات مطوري البرامج" في Chrome Canary، تُبرز لوحة "نقاط التوقف عن الاستماع إلى الأحداث" في لوحة "المصادر"
يتم اختيار "بدء مرحلة عروض أسعار نظام عروض الأسعار" ضمن "وظيفة مزاد الإعلانات".

عند تشغيل نقطة توقف، يتم إيقاف التنفيذ مؤقتًا قبل العبارة الأولى في المستوى الأعلى من نص الواجب. يمكنك استخدام نقاط التوقف المنتظمة أو أوامر الخطوات للوصول إلى وظيفة عروض الأسعار/النتائج/التقارير نفسها.

ستظهر النصوص البرمجية المباشرة في Worklet أيضًا ضمن لوحة سلاسل المحادثات.

لقطة شاشة لـ
"أدوات مطوري البرامج" في Chrome Canary تُبرز لوحة سلاسل المحادثات في لوحة "المصادر"، وتعرض النص البرمجي الحالي
للعمل الأساسي الذي تم إيقافه مؤقتًا

وبما أنّ بعض الوظائف المصغّرة قد تعمل بشكل متوازٍ، قد تصبح سلاسل التعليمات "متوقفة مؤقتًا" هناك، لذلك يمكنك استخدام قائمة سلاسل المحادثات للتبديل بين سلاسل التعليمات واستئنافها أو فحصها عن كثب حسبما تقتضي الحاجة.

تتبُّع أحداث الجمهور المحمي

من لوحة "التطبيقات" ضِمن "أدوات مطوري البرامج في Chrome"، يمكنك الاطّلاع على أحداث المزادات ومجموعات اهتمامات الجمهور المحمي.

إذا انتقلت إلى موقع التسوّق التجريبي Protected Audience في متصفّح تم فيه تفعيل Protected Audience، ستعرض "أدوات مطوّري البرامج" معلومات عن حدث "join".

لوحة تطبيق "أدوات مطوري البرامج" في Chrome Canary، تعرض معلومات حول حدث انضمام إلى مجموعة اهتمامات للجمهور المحمي.

الآن، إذا انتقلت إلى الموقع الإلكتروني للناشر الخاص بالعرض التوضيحي للجمهور المحمي في متصفّح تم فيه تفعيل "الجمهور المحمي"، ستعرِض "أدوات مطوّري البرامج" معلومات عن حدثَي bid وwin.

لوحة تطبيق
أدوات مطوّري البرامج في Chrome Canary، تعرض معلومات حول عرض أسعار مزاد الجمهور المحمي
والفوز بالأحداث.

ما هي آلية عمل Protected Audience API؟

في هذا المثال، يتصفح أحد المستخدمين الموقع الإلكتروني لصانع دراجة مخصص، ثم يزور في وقت لاحق موقعًا إلكترونيًا إخباريًا ويظهر في وقت لاحق إعلان لدراجة جديدة من صانع الدراجة.

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

1- يزور أحد المستخدِمين أحد المواقع الإلكترونية لأحد المعلِنين.

صورة توضيحية تعرض شخصًا يزور موقعًا إلكترونيًا مخصّصًا لتصنيع الدراجات في متصفّح على الكمبيوتر المحمول

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

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

2- يُطلب من متصفّح المستخدم إضافة مجموعة اهتمامات.

صورة توضيحية تعرض شخصًا يشاهد موقعًا إلكترونيًا في متصفّح على الكمبيوتر المحمول يتم تشغيل رمز JavaScript
joinAdinterestGroup() في المتصفّح.

قسم الشرح: تسجيل مجموعات الاهتمامات في المتصفِّحات

يستدعي نظام عرض الطلب (DSP) الذي يستخدمه المعلن (أو المعلن نفسه) navigator.joinAdInterestGroup() ليطلب من المتصفّح إضافة مجموعة اهتمامات إلى قائمة المجموعات التي ينتمي إليها المتصفّح. في هذا المثال، تُسمى المجموعة custom-bikes والمالك هو dsp.example. سيكون مالك مجموعة الاهتمامات (في هذه الحالة، وسيط عرض الطلب) مشتريًا في مزاد الإعلانات الموضّح في الخطوة 4. يخزّن المتصفح أو على جهاز المستخدم عضوية مجموعة الاهتمامات، ولا تتم مشاركتها مع مورّد المتصفّح أو أي جهة أخرى.

ملاحظة: يجب أن يتطابق أصل سياق الاتصال في joinAdInterestGroup() مع أصل مالك مجموعة الاهتمامات، لذلك يجب طلب joinAdInterestGroup() من إطار iframe (على سبيل المثال، من نظام وسيط عرض الطلب) ما لم يطابق أصل مالك مجموعة الاهتمامات مصدر المستند الحالي (على سبيل المثال، موقع إلكتروني يحتوي على مجموعات الاهتمامات الخاصة به). لا يتضمّن تطبيق runAdAuction المتطلبات نفسها، لذا من المحتمل أن يكون استدعاء runAdAuction() من علامة <script> أفضل بكثير من استدعاء إطار iframe من مصادر متعددة.

يتطلب joinAdInterestGroup() إذنًا من: * الموقع الإلكتروني الذي تتم زيارته * مالك مجموعة الاهتمامات

على سبيل المثال: يجب ألا يتمكّن "malicious.example" من الاتصال بـ joinAdInterestGroup() "dsp.example" كمالك بدون الحصول على إذن dsp.example.

الإذن من الموقع الإلكتروني الذي تتم زيارته

المصدر نفسه: بشكل تلقائي، يتم منح الإذن بشكل ضمني لاستدعاءات joinAdInterestGroup() الواردة من المصدر نفسه الذي ينتقل إليه الموقع الإلكتروني الذي تتم زيارته، أي من المصدر نفسه للإطار ذي المستوى الأعلى للصفحة الحالية. يمكن للمواقع الإلكترونية استخدام عنوان سياسة الأذونات join-ad-interest-group لإيقاف طلبات joinAdInterestGroup() الجمهور المحمي.

من مصادر متعددة: لا يمكن استدعاء joinAdInterestGroup() من مصادر مختلفة عن الصفحة الحالية إلا إذا ضبط الموقع الإلكتروني الذي تتم زيارته سياسة أذونات تسمح باستدعاء joinAdInterestGroup() من إطارات iframe من مصادر متعددة.

ملاحظة: الإعداد التلقائي في التنفيذ الحالي لـ Protected Audience هو السماح بالمكالمات إلى joinAdInterestGroup() من أيّ مكان في الصفحة، حتى من إطارات iframe من مصادر متعددة. في المستقبل، عندما يتوفّر لمالكي المواقع الإلكترونية الوقت لتعديل سياسات الأذونات الخاصة بهم، سيتم تلقائيًا منع الطلبات الواردة من إطارات iframe من مصادر متعددة، كما هو موضّح في شرح Protected Audience.

إذن من مالك مجموعة الاهتمامات

يتم منح إذن مالك مجموعة الاهتمامات ضمنيًا من خلال استدعاء joinAdInterestGroup() من إطار iframe له بنفس مصدر مالك مجموعة الاهتمامات. على سبيل المثال، يمكن لإطار iframe dsp.example استدعاء joinAdInterestGroup() لمجموعات الاهتمامات التي يملكها dsp.example.

الاقتراح هو أنّه يمكن تشغيل joinAdInterestGroup() في صفحة أو إطار iframe في نطاق المالك، أو أن يتم تفويضه لنطاقات أخرى مقدَّمة باستخدام قائمة على عنوان URL .well-known.

استخدام navigator.joinAdinterestGroup()

في ما يلي مثال على كيفية استخدام واجهة برمجة التطبيقات:

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

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

نقطة رئيسية: يجب أن تكون جميع عناوين URL المستخدَمة كمَعلمات لطُرق Protected Audience API مصدرها آمن، إذ يجب عرض جميع الموارد من خلال عناوين URL تستخدم HTTPS. يوضّح كيفية استخدام HTTPS للتطوير المحلي كيفية إجراء ذلك عند تشغيل Protected Audience على الجهاز. بالإضافة إلى ذلك، يتطلّب كل من biddingLogicUrl وdecisionLogicUrl وtrustedBiddingSignals عنوان استجابة HTTP X-Allow-FLEDGE: true.

خصائص مجموعة الاهتمامات

الموقع	مطلوبة	مثال	Role
`owner`	مطلوبة	`'https://dsp.example'`	مصدر مالك مجموعة الاهتمامات.
`name`	مطلوبة	`'custom-bikes'`	اسم مجموعة الاهتمامات.
`biddingLogicUrl`**	اختياري*	`'https://dsp.example/bid/custom-bikes/bid.js'`	عنوان URL لعرض أسعار JavaScript يتم تشغيله في Worklet
`biddingWasmHelperUrl`**	اختياري*	`'https://dsp.example/bid/custom-bikes/bid.wasm'`	عنوان URL لرمز WebAssembly الصادر من `biddingLogicUrl`.
`dailyUpdateUrl`**	اختياري	`'https://dsp.example/bid/custom-bikes/update'`	عنوان URL يعرض JSON لتعديل سمات مجموعة الاهتمامات. (راجِع تعديل مجموعة الاهتمامات.)
`trustedBiddingSignalsUrl`**	اختياري	`'https://dsp.example/trusted/bidding-signals'`	عنوان URL الأساسي لطلبات القيم الأساسية المرسَلة إلى الخادم الموثوق به لمقدّم عروض الأسعار.
`trustedBiddingSignalsKeys`	اختياري	`['key1', 'key2' ...]`	مفاتيح الطلبات للخادم الموثوق به الذي يحمل قيمة أساسية.
`userBiddingSignals`	اختياري	`{...}`	بيانات وصفية إضافية يمكن للمالك استخدامها أثناء تقديم عروض الأسعار
`ads`	اختياري*	`[bikeAd1, bikeAd2, bikeAd3]`	الإعلانات التي يمكن عرضها لمجموعة الاهتمامات هذه.
`adComponents`	اختياري	`[customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]`	مكوّنات الإعلانات المؤلفة من عدة أجزاء.

* جميع السمات اختيارية باستثناء owner وname. السمتان biddingLogicUrl وads اختياريتان، ولكنّهما مطلوبتان للمشاركة في مزاد. قد تكون هناك حالات استخدام لإنشاء مجموعة اهتمامات بدون هذه السمات: على سبيل المثال، قد يرغب مالك مجموعة الاهتمامات في إضافة متصفّح إلى مجموعة اهتمام لحملة لم يتم إطلاقها بعد، أو لأغراض أخرى أخرى في المستقبل، أو ربما نفدت ميزانيته الإعلانية له مؤقتًا.

** يجب أن يكون عنوان URL الخاص بـ biddingLogicUrl وbiddingWasmHelperUrl وdailyUpdateUrl وtrustedBiddingSignalsUrl هو المصدر نفسه الخاص بالمالك. ولا يتضمّن عنوانا URL ads وadComponents هذا القيد.

تعديل سمات مجموعات الاهتمامات

تحدّد dailyUpdateUrl خادم ويب يعرض خصائص JSON المحدَّدة الخاصة بمجموعة الاهتمامات، وذلك بالتوافق مع كائن مجموعة الاهتمامات الذي تم تمريره إلى navigator.joinAdInterestGroup(). ويوفّر ذلك آلية لمالك المجموعة لتعديل سماتها بشكل دوري. في طريقة التنفيذ الحالية، يمكن تغيير السمات التالية:

biddingLogicUrl
biddingWasmHelperUrl
trustedBiddingSignalsUrl
trustedBiddingSignalsKeys
ads
priority

ولن يتم استبدال أي حقل غير محدّد في JSON، بل يتم فقط تعديل الحقول المحدّدة في JSON، بينما يؤدي استدعاء navigator.joinAdInterestGroup() إلى استبدال أي مجموعة اهتمام حالية.

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

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

تحديثات يدوية

يمكن إجراء تعديلات يدويًا على مجموعات الاهتمامات التي يملكها مصدر الإطار الحالي من خلال navigator.updateAdInterestGroups(). يؤدي الحدّ الأقصى لمعدّل الزحف إلى منع إجراء التحديثات بشكل متكرّر، فإن المكالمات المتكررة إلى navigator.updateAdInterestGroups() لا تؤدي إلى اتخاذ أي إجراء إلا بعد انقضاء فترة الحدّ الأقصى لمعدّل الزحف (حاليًا يوم واحد). تتم إعادة ضبط الحدّ الأقصى لمعدّل الزحف في حال طلب "navigator.joinAdInterestGroup()" مرة أخرى لمجموعة الاهتمامات نفسها "owner" و"name".

التحديثات التلقائية

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

تحديد إعلانات لمجموعة اهتمامات

يتضمّن عنصرا ads وadComponents عنوان URL لتصميم الإعلان، بالإضافة إلى بيانات وصفية عشوائية يمكن استخدامها في وقت تقديم عروض الأسعار، إذا رغبت في ذلك. مثال:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

كيف يقدّم المشترون عروض الأسعار؟

يجب أن يشتمل النص البرمجي في biddingLogicUrl الذي يقدمه مالك مجموعة الاهتمامات على دالة generateBid(). عندما يستدعي بائع مساحة إعلانية navigator.runAdAuction()، يتم استدعاء الدالة generatedBid() مرة واحدة لكل مجموعة من مجموعات الاهتمامات التي ينتمي إليها المتصفّح، في حال دعوة مالك مجموعة الاهتمامات لتقديم عرض سعر. بعبارة أخرى، يتم استدعاء generateBid() مرة واحدة لكل إعلان مرشّح. يوفّر البائع السمة decisionLogicUrl في مَعلمة إعداد المزاد التي تم ضبطها إلى navigator.runAdAuction(). يجب أن يتضمّن الرمز في عنوان URL هذا دالة scoreAd() يتم تشغيلها لكل مقدِّم عرض سعر في المزاد لتقييم كل عرض من عروض الأسعار التي يعرضها generateBid().

ملاحظة: إنّ السمة biddingWasmHelperUrl اختيارية، ولكنها تسمح لمقدّم عروض الأسعار بتوفير إجراءات فرعية مكلّفة من الناحية الحسابية في WebAssembly، بدلاً من JavaScript، من أجل الحصول عليها من دالة JavaScript التي يوفّرها biddingLogicUrl. ويجب أن يشير الرمز، في حال توفُّره، إلى برنامج WebAssembly الثنائي الذي يتم إرساله مع application/wasm mimetype. ويتم توفير WebAssembly.Module المقابل من خلال المتصفح للوظيفة generateBid().

يجب أن يشتمل النص البرمجي في biddingLogicUrl الذي يقدمه مشترٍ للمساحة الإعلانية على دالة generateBid(). يتم استدعاء هذه الدالة مرة واحدة لكل إعلان مرشّح. runAdAuction() يفحص كل إعلان بشكل فردي، بالإضافة إلى عرض السعر والبيانات الوصفية المرتبطة به، ثم يعيّن درجة الرغبة الرقمية للإعلان.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

يستخدم generateBid() الوسيطات التالية:

interestGroup
أرسل مشتري الإعلان العنصر إلى joinAdInterestGroup(). (يمكن تعديل مجموعة الاهتمامات من خلال "dailyUpdateUrl").
auctionSignals
سمة لوسيطة إعدادات المزاد التي تم تمريرها إلى navigator.runAdAuction() من خلال البائع في المساحة الإعلانية. وهذا يوفر معلومات حول سياق الصفحة (مثل حجم الإعلان والرقم التعريفي للناشر) ونوع المزاد (السعر الأول أو السعر الثاني) والبيانات الوصفية الأخرى.
perBuyerSignals
كما هو الحال في auctionSignals، مرر البائع موقع في وسيطة ضبط المزاد إلى navigator.runAdAuction(). ويمكن أن يوفر ذلك إشارات سياقية من خادم المشتري حول الصفحة، إذا كان البائع عبارة عن نظام SSP (يجري طلبًا يستند إلى عروض الأسعار في الوقت الفعلي) على خوادم المشتري ويوجّه الرد إليها، أو إذا اتصلت صفحة الناشر بخادم المشتري مباشرةً. في هذه الحالة، قد يرغب المشتري في التحقق من توقيع تشفير لهذه الإشارات داخل generateBid() كحماية ضد العبث.
trustedBiddingSignals
كائنًا تكون مفاتيحه trustedBiddingSignalsKeys لمجموعة الاهتمامات، ويتم عرض قيمه في طلب trustedBiddingSignals.
browserSignals
عنصر أنشأه المتصفّح، وقد يتضمّن معلومات حول سياق الصفحة (مثل hostname من الصفحة الحالية، التي يمكن للبائع تزييفها) وبيانات مجموعة الاهتمامات نفسها (مثل سجل لفوز المجموعة في السابق بمزاد، للسماح بتحديد عدد مرّات الظهور على الجهاز فقط)

يحتوي الكائن browserSignals على السمات التالية:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

لاحتساب قيمة bid، يمكن للرمز في generateBid() استخدام خصائص معلَمات الدالة. مثال:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

تعرض دالة generateBid() كائنًا بأربع خصائص:

ad
بيانات وصفية عشوائية عن الإعلان، مثل المعلومات التي يتوقّع البائع أن يعرفها عن عرض السعر هذا أو تصميم الإعلان. يستخدم البائع](/privacy-sandbox/resources/vocabulary#ssp) هذه المعلومات في مزاد الإعلانات وتصميمات الإعلان. يستخدم البائع هذه المعلومات في مزاد الإعلانات ومنطق اتخاذ القرار.
bid
عرض سعر رقمي يدخل المزاد يجب أن يكون البائع في وضع يسمح له بمقارنة عروض الأسعار من مشترين مختلفين، وبالتالي يجب أن تكون عروض الأسعار في وحدة يختارها البائع (على سبيل المثال "دولار أمريكي لكل ألف"). وإذا كان عرض السعر صفرًا أو سالبًا، لن تشارك مجموعة الاهتمامات هذه في مزاد البائع على الإطلاق. وباستخدام هذه الآلية، يمكن للمشتري تنفيذ أي قواعد خاصة بالمعلِنين في ما يتعلق بالأماكن التي قد تظهر أو لا تظهر فيها إعلاناتهم.
render
عنوان URL أو قائمة عناوين URL التي سيتم استخدامها لعرض تصميم الإعلان في حال فوز عرض السعر هذا بالمزاد. (اطّلع على الإعلانات المؤلفة من عدة أجزاء في شرح واجهة برمجة التطبيقات). يجب أن تتطابق القيمة مع renderUrl لأحد الإعلانات المحدّدة لمجموعة الاهتمامات.
adComponents
قائمة اختيارية تضم ما يصل إلى 20 مكوّنًا للإعلانات المكوّنة من عدة أجزاء، مأخوذة من السمة adComponents الخاصة بوسيطة مجموعة الاهتمامات التي تم تمريرها إلى navigator.joinAdInterestGroup().

مطالبة المتصفح بمغادرة مجموعة اهتمام

يمكن لمالك مجموعة الاهتمامات طلب إزالة متصفّح من مجموعة الاهتمامات. وبعبارة أخرى، يُطلب من المتصفّح إزالة المجموعة ذات الاهتمامات المشتركة من قائمة المجموعة التي ينتمي إليها.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

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

3. زيارة المستخدم لموقع إلكتروني يبيع مساحة إعلانية

صورة توضيحية تعرض شخصًا يزور موقعًا إلكترونيًا إخباريًا في متصفّح على كمبيوتر محمول يحتوي الموقع الإلكتروني على شريحة إعلانية فارغة.

وبعد ذلك، يزور المستخدِم موقعًا إلكترونيًا يبيع مساحة إعلانية، في هذا المثال موقع إلكتروني إخباري. يحتوي الموقع الإلكتروني على مستودع إعلانات يبيعه آليًا باستخدام عروض أسعار الوقت الفعلي.

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

4- يتم إجراء مزاد إعلانات في المتصفح

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

قسم التفسير: البائعون يجرون مزادات على الأجهزة

من المرجح أن يتم إجراء مزاد الإعلانات من قِبل SSP للناشر أو الناشر نفسه. الغرض من المزاد هو اختيار الإعلان الأنسب لشريحة إعلانية واحدة متاحة على الصفحة الحالية. يأخذ المزاد في الاعتبار مجموعات الاهتمامات التي ينتمي إليها المتصفّح، إلى جانب بيانات مستمَدة من المشترين في المساحات الإعلانية والبائعين من خدمات المفاتيح/القيمة.

يرسل البائع في المساحة الإعلانية طلبًا إلى متصفّح المستخدم لبدء مزاد إعلانات من خلال الاتصال بالرقم navigator.runAdAuction().

مثال:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

تعرض دالة runAdAuction() وعدًا يتم حلّه إلى URN (urn:uuid:<something>) يمثّل نتيجة مزاد الإعلانات. ولا يمكن فك ترميز هذا المحتوى إلا بواسطة المتصفّح عند تمريره إلى إطار مضمّن للعرض: لا يمكن لصفحة الناشر فحص الإعلان الفائز.

ملاحظة: كما هو موضّح سابقًا، يجب أن يتطابق أصل سياق الاتصال للسمة joinAdInterestGroup() مع أصل مالك مجموعة الاهتمامات، لذلك يجب طلب joinAdInterestGroup() من إطار iframe (على سبيل المثال، من نظام وسيط عرض الطلب (DSP)) ما لم يتطابق أصل مالك مجموعة الاهتمامات مع مصدر المستند الحالي (على سبيل المثال، موقع إلكتروني له مجموعات الاهتمامات الخاصة به). لا يتضمّن تطبيق runAdAuction المتطلبات نفسها، لذا من المحتمل أن يكون استدعاء runAdAuction() من علامة <script> أفضل بكثير من استدعاء إطار iframe من مصادر متعددة.

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

`auctionConfig` مكانًا للإقامة

الموقع	مطلوبة	مثال	Role
`seller`	مطلوبة	`'https://ssp.example'`	مصدر البائع.
`decisionLogicUrl`	مطلوبة	`'https://ssp.example/auction-decision-logic.js'`	عنوان URL لمكوّن JavaScript المصغَّر
`trustedScoringSignalsUrl`	اختياري	`'https://ssp.example/scoring-signals'`	عنوان URL للخادم الموثوق به للبائع.
`interestGroupBuyers*`	مطلوبة	`['https://dsp.example', 'https://buyer2.example', ...]`	مصادر جميع مالكي مجموعات الاهتمامات الذين طلبوا تقديم عروض أسعار في المزاد.
`auctionSignals`	اختياري	`{...}`	معلومات البائع حول سياق الصفحة ونوع المزاد وما إلى ذلك
`sellerSignals`	اختياري	`{...}`	المعلومات المستندة إلى إعدادات الناشر، وتقديم طلب إعلان سياقي، إلخ.
`sellerTimeout`	اختياري	`100`	الحد الأقصى لوقت تشغيل النص البرمجي `scoreAd()` للبائع
`perBuyerSignals`	اختياري	`{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ...}`	إشارات سياقية حول الصفحة لكل مشترٍ معيّن، من الخادم.
`perBuyerTimeouts`	اختياري	`50`	الحد الأقصى لوقت تشغيل النصوص البرمجية `generateBid()` الخاصة بمشتري معيّن
`componentAuctions`	اختياري	`[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]`	تكوينات إضافية لمزادات المكوّنات.

* يجوز للبائع تحديد interestGroupBuyers: '*' للسماح لكل مجموعات الاهتمامات بتقديم عروض أسعار. وبعد ذلك، يتم قبول الإعلانات أو رفضها استنادًا إلى معايير أخرى غير تضمين مالك مجموعة الاهتمامات. على سبيل المثال، يجوز للبائع مراجعة تصاميم الإعلانات للتأكّد من التزامها بسياساته.

** لا يتوفّر عمود additionalBids في التنفيذ الحالي لميزة "الجمهور المحمي". لمزيد من المعلومات، يُرجى الاطّلاع على قسم المشاركون في المزاد ضمن المقالة التوضيحية Protected Audience API.

كيف يتم اختيار الإعلانات؟

يجب أن يشتمل الرمز في decisionLogicUrl (خاصية لكائن إعداد المزاد الذي تم تمريره إلى runAdAuction()) على دالة scoreAd(). يتم تشغيل هذا التقرير مرة واحدة لكل إعلان لتحديد مدى استحسانه

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

تستخدم scoreAd() الحجج التالية: * adMetadata
بيانات وصفية عشوائية يقدّمها المشتري. * bid
قيمة عددية لعرض السعر * auctionConfig
تم تمرير عنصر إعداد المزاد إلى navigator.runAdAuction(). * trustedScoringSignals
القيم التي تم استردادها في وقت المزاد من الخادم الموثوق به للبائع تمثل رأي البائع في الإعلان * browserSignals
عنصر تم إنشاؤه بواسطة المتصفح، بما في ذلك المعلومات التي يعرفها المتصفح والتي قد يحتاج النص البرمجي لمزاد البائع إلى التحقق منها:

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

قبل بدء المزاد، يعثر البائع على أفضل إعلان سياقي للشريحة الإعلانية المتاحة. جزء من منطق scoreAd() هو رفض أي إعلان لا يمكنه التفوق على الإعلان الفائز السياقي.

5- يتلقّى البائع والمشترين المشاركون بيانات في الوقت الفعلي من خدمة المفتاح/القيمة.

صورة توضيحية تعرض شخصًا يشاهد موقعًا إلكترونيًا إخباريًا في متصفّح على كمبيوتر محمول يتم إجراء مزاد إعلانات باستخدام Protected Audience API، ويحصل أحد المشاركين على بيانات من خدمة "المفتاح/القيمة".

قسم التفسير: جلب البيانات في الوقت الفعلي من خدمة "قيمة/مفتاح الجمهور المحمي".

خلال مزاد الإعلانات، يمكن أن يحصل البائع في المساحة الإعلانية على بيانات في الوقت الفعلي عن تصاميم إعلانات معيّنة عن طريق تقديم طلب إلى خدمة المفاتيح/القيمة باستخدام السمة trustedScoringSignalsUrl في وسيطة ضبط المزاد التي تم تمريرها إلى navigator.runAdAuction()، إلى جانب المفاتيح من سمات renderUrl لجميع الإدخالات في الحقلين ads وadComponents لجميع مجموعات الاهتمامات في المزاد.

وبالمثل، يمكن لمشتري المساحة الإعلانية طلب بيانات في الوقت الفعلي من خدمة "المفتاح/القيمة" باستخدام السمتَين trustedBiddingSignalsUrl وtrustedBiddingSignalsKeys في وسيطة مجموعة الاهتمامات التي تم تمريرها إلى navigator.joinAdInterestGroup().

عند استدعاء "runAdAuction()"، يقدّم المتصفح طلبًا إلى الخادم الموثوق به لكل مشترٍ للإعلانات. قد يبدو عنوان URL للطلب كما يلي:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2

يأتي عنوان URL الأساسي من trustedBiddingSignalsUrl.
يوفّر المتصفّح hostname.
القيمة keys مأخوذة من trustedBiddingSignalsKeys.

والاستجابة لهذا الطلب هي كائن JSON يوفر قيمًا لكل مفتاح من المفاتيح.

نقطة رئيسية: في المرحلة التجريبية الأولية الحالية لاختبار ميزة "الجمهور المحمي"، يجب أن يكون لدى "trustedBiddingSignalsUrl" المصدر نفسه لمالك مجموعة الاهتمامات: اطّلِع على سمات مجموعة الاهتمامات وإحضار خادمك الخاص.

6- يتم عرض الإعلان الفائز.

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

قسم الشرح: تعرض المتصفحات الإعلان الفائز.

كما هو موضّح سابقًا: يتم تحويل الوعد الذي تعرضه runAdAuction() إلى URN الذي يتم تمريره إلى إطار مسيّج للعرض، ويعرض الموقع الإلكتروني الإعلان الفائز.

7- يتم الإبلاغ عن نتيجة المزاد

قسم الشرح: إعداد التقارير على مستوى الحدث (حاليًا)

ملاحظة: تتمثّل الخطة الطويلة الأجل في تفعيل المتصفّح من إعداد تقارير عن نتائج المزاد للبائع والمشترين باستخدام واجهات برمجة التطبيقات لإعداد التقارير المجمّعة. كآلية إعداد تقارير مؤقتة على مستوى الحدث، يمكن للرمز الذي ينفّذ reportResult() للبائع والرمز reportWin() لمقدّم عرض السعر الفائز استدعاء الدالة sendReportTo(). ويشمل ذلك وسيطة واحدة، وهي سلسلة تمثّل عنوان URL يتم جلبه بعد اكتمال المزاد، والتي تشفّر المعلومات على مستوى الحدث المطلوب إعداد تقارير عنها.

نتيجة بلاغات البائع

قسم التفسير: تقارير البائعين حول العرض

يمكن أن تتضمّن لغة JavaScript الخاصة بالبائع والمتوفّرة في decisionLogicUrl (والتي توفّرت أيضًا السمة scoreAd()) الدالة reportResult() للإبلاغ عن نتيجة المزاد.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

الوسيطات التي تم تمريرها إلى هذه الدالة هي:

auctionConfig
تم تمرير عنصر إعداد المزاد إلى navigator.runAdAuction().

browserSignals
عنصر تم إنشاؤه بواسطة المتصفح الذي يقدّم معلومات عن المزاد. على مثال:

{
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

يتمّ استخدام القيمة المعروضة لهذه الدالة كوسيطة sellerSignals لدالة reportWin() الخاصة بمقدِّم عرض السعر الفائز.

نتيجة تقارير مقدِّم عرض السعر الفائز

قسم التفسير: تقارير المشترين حول العرض وأحداث الإعلانات

ويمكن أن تتضمّن لغة JavaScript لمقدِّم عرض السعر الفائز (التي وفّرت أيضًا السمة generateBid()) وظيفة reportWin() للإبلاغ عن نتيجة المزاد.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

ملاحظة: سيصدر تحذير بشأن التنفيذ الحالي لـ Protected Audience في Chrome في حال عدم تحديد السمة reportWin().

الوسيطات التي تم تمريرها إلى هذه الدالة هي:

auctionSignals وperBuyerSignals
تم تمرير القيم نفسها إلى generateBid() لصاحب عرض السعر الفائز.
sellerSignals
القيمة المعروضة هي reportResult()، ما يمنح البائع فرصة لتمرير المعلومات إلى المشتري.

browserSignals
عنصر تم إنشاؤه بواسطة المتصفّح الذي يقدّم معلومات عن المزاد على مثال:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

تنفيذ تقارير الخسارة/الربح المؤقتة

تتوفّر طريقتان متاحتان مؤقتًا في Chrome لإعداد تقارير المزادات:

forDebuggingOnly.reportAdAuctionLoss()
forDebuggingOnly.reportAdAuctionWin()

تأخذ كل طريقة من هاتين الطريقتين وسيطة واحدة: عنوان URL لجلبه بعد اكتمال المزاد. ويمكن استدعائها عدة مرات في كل من scoreAd() وgenerateBid() باستخدام وسيطات عناوين URL مختلفة.

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

تتوفّر هذه الطرق تلقائيًا في Chrome إذا كان chrome://flags/#privacy-sandbox-ads-apis مفعَّلاً. وإذا كنت تشغِّل Chrome باستخدام علامات سطر الأوامر لتفعيل Protected Audience، يجب تفعيل الطرق بشكل صريح من خلال تضمين العلامة BiddingAndScoringDebugReportingAPI. وفي حال عدم تفعيل العلامة، ستظل الطرق متاحة ولكن لا يفعل أي شيء.

8- يتم الإبلاغ عن نقرة على إعلان

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

يتم الإبلاغ عن نقرة على إعلان يتم عرضه في إطار مضمّن. لمزيد من المعلومات عن آلية عمل ذلك، اطّلِع على إعداد تقارير إعلانات الإطارات المضمّنة في Fenced Frames.

يوضِّح المخطّط البياني التالي كلّ مرحلة من مراحل مزاد الإعلانات للجمهور المحمي:

صورة توضيحية تقدّم نظرة عامة على كل مرحلة من مراحل مزاد الإعلانات المستندة إلى الجمهور المحمي

ما الفرق بين "الجمهور المحمي" وأداة TURTLEDOVE؟

Protected Audience هي أوّل تجربة يتم تنفيذها في Chromium ضمن مجموعة اقتراحات TURTLEDOVE.

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

تهدف مبادرة TURTLEDOVE إلى تقديم واجهة برمجة تطبيقات جديدة لمعالجة حالة الاستخدام هذه مع توفير بعض التطورات الرئيسية في الخصوصية:

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

نشأ Protected Audience من TURTLEDOVE ومجموعة من المقترحات ذات الصلة للتعديلات من أجل تقديم خدمة أفضل للمطوّرين الذين سيستخدمون واجهة برمجة التطبيقات:

في SPARROW: اقترح Criteo إضافة نموذج خدمة ("Gatekeeper") يعمل في بيئة تنفيذ موثوق بها (TEE). تشمل ميزة Protected Audience استخدامًا محدودًا بشكل أكبر لـ " بيئة التنفيذ الموثوقة" (TEE)، وذلك للبحث عن البيانات في الوقت الفعلي وإعداد التقارير المجمَّعة.
وصف اقتراحا TERN وMignite من NextRoll PARRROT الأدوار المختلفة للمشترين والبائعين في المزاد على الجهاز فقط. ويستند مسار عروض أسعار الإعلانات أو النتائج في "مبادرة حماية الجمهور" إلى هذه الإجراءات.
تم تحسين إمكانات التخصيص ونموذج إخفاء الهوية في المزاد على الجهاز من خلال تعديلات TURTLEDOVE المستندة إلى النتائج وعلى مستوى المنتج في RTB
PARAKEET هي اقتراح من Microsoft لخدمة إعلانية تشبه TURTLEDOVE وتعتمد على خادم وكيل يعمل في بيئة التنفيذ الموثوقة (TEE) بين المتصفّح ومزوّدي تقنية الإعلان، وذلك لإخفاء هوية طلبات الإعلانات وفرض خصائص الخصوصية. لم تستخدِم ميزة Protected Audience نموذج الخادم الوكيل هذا. نحن بصدد دمج واجهات برمجة تطبيقات JavaScript التي تخصّ PARAKEET وProtected Audience API، لدعم العمل المستقبلي لدمج أفضل ميزات كلا العرضين.

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

ما هي إعدادات المتصفِّح المتاحة؟

يمكن للمستخدمين تعديل مشاركتهم في الفترات التجريبية التي تخصّ "مبادرة حماية الخصوصية" في Chrome من خلال تفعيل إعدادات المستوى الأعلى أو إيقافها في chrome://settings/adPrivacy. أثناء الاختبار الأوّلي، سيتمكّن المستخدمون من استخدام هذا الإعداد العالي المستوى في "مبادرة حماية الخصوصية" لإيقاف ميزة Protected Audience. يخطط Chrome للسماح للمستخدمين برؤية وإدارة قائمة المجموعات ذات الاهتمامات المشتركة التي تمت إضافتهم إليها عبر المواقع الإلكترونية التي زاروها. كما هو الحال مع تقنيات "مبادرة حماية الخصوصية" نفسها، قد تتطوّر إعدادات المستخدم بالاستناد إلى الملاحظات الواردة من المستخدمين والهيئات التنظيمية وغيرهم.

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

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

التفاعل ومشاركة الملاحظات

GitHub: يمكنك قراءة الاقتراح، وطرح الأسئلة ومتابعة المناقشة.
W3C: مناقشة حالات الاستخدام في المجال في مجموعة أعمال تحسين الإعلانات على الويب
دعم المطوّرين: يمكنك طرح أسئلة والمشاركة في مناقشات حول تقرير دعم المطوّرين في "مبادرة حماية الخصوصية".
القائمة البريدية FLEDGE: توفر fledge-api-announce إشعارات وتحديثات حول واجهة برمجة التطبيقات.
الانضمام إلى المكالمات المُجدوَلة لميزة "الجمهور المحمي" (كل أسبوع). نرحّب بالجميع للانضمام إلى المنتدى، لذا يجب أولاً الانضمام إلى مجموعة WICG. يمكنك المشاركة بنشاط أو مجرد الاستماع!
استخدِم نموذج الملاحظات الخاص بـ "مبادرة حماية الخصوصية" لمشاركة الملاحظات بشكل خاص مع فريق Chrome خارج المنتديات العامة.

الحصول على الدعم

لطرح سؤال حول عملية التنفيذ أو عن العرض التوضيحي أو عن المستندات: * فتح مشكلة جديدة في مستودع privacy-sandbox-dev-support تأكَّد من اختيار نموذج المشكلة في Protected Audience. * يُرجى طرح مشكلة في مستودع الرموز التجريبية على GitHub. * لمزيد من الأسئلة العامة حول كيفية استيفاء حالات الاستخدام لواجهة برمجة التطبيقات، يمكنك الإبلاغ عن مشكلة في مستودع العروض.

بالنسبة إلى الأخطاء والمشاكل المتعلقة بتنفيذ واجهة برمجة التطبيقات Protected Audience API في Chrome: * عرض المشاكل الحالية التي تم الإبلاغ عنها في واجهة برمجة التطبيقات * يمكنك طرح مشكلة جديدة على crbug.com/new.

البقاء على اطّلاع

لتلقّي إشعارات بشأن تغييرات الحالة في واجهة برمجة التطبيقات، يمكنك الانضمام إلى القائمة البريدية لمطوّري البرامج.
لمتابعة جميع المناقشات الجارية حول واجهة برمجة التطبيقات عن كثب، انقر على الزر مشاهدة في صفحة الاقتراحات على GitHub. يتطلب ذلك أن يكون لديك أو حساب GitHub.
للحصول على آخر الأخبار العامة حول "مبادرة حماية الخصوصية"، يُرجى الاشتراك في خلاصة RSS [التقدّم في مبادرة حماية الخصوصية].

التعرف على المزيد

Protected Audience API: نظرة عامة أقلّ تقنية على الاقتراح.
الإصدار التجريبي من Protected Audience: يمكنك الاطّلاع على جولة تفصيلية حول نشر الميزة الأساسية للجمهور المحمي.
الفيديو التوضيحي حول Protected Audience: يشرح هذا الفيديو الرمز البرمجي التجريبي ويوضّح كيفية استخدام "أدوات مطوري البرامج في Chrome" لتصحيح الأخطاء المتعلقة بالجمهور المحمي.
الشرح الفني لـ Protected Audience API
فهم أعمق في "مبادرة حماية الخصوصية"
إنشاء نموذج أولي

تصوير راي هينيسي على UnLaunch.