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

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

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

تُعدّ هذه المشاركة مرجعًا فنيًا إلى التكرار الحالي للإصدار التجريبي من Protected Audience API.

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

ما هي ميزة Protected Audience؟

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

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

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

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

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

الإصدار التجريبي من Protected Audience

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

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

المشاركة في مرحلة التجربة والتقييم في Protected Audience

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

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

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

يقدِّم العرض التوضيحي لميزة Protected Audience مثالاً أساسيًا على عملية نشر 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 الذي يشغِّل رمز Protected Audience، مثل طلب navigator.joinAdInterestGroup() من قِبل مالك مجموعة الاهتمامات، إلى توفير رمز مميّز يتطابق مع مصدره.

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

اختبار واجهة برمجة التطبيقات هذه

يمكنك اختبار Protected Audience لمستخدم واحد في الإصدار التجريبي 101.0.4951.26 من Chrome والإصدارات الأحدث على أجهزة الكمبيوتر المكتبي:

من خلال تفعيل جميع واجهات برمجة تطبيقات الخصوصية في عرض الإعلانات ضِمن "chrome://settings/adPrivacy"
عن طريق وضع علامات من سطر الأوامر.

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

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

لاستخدام <fencedframe> لعرض الإعلانات:

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

لاستخدام <iframe> لعرض الإعلانات:

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

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

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

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

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

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

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

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

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

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

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

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

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

لضمان توفُّر ما يكفي من الوقت لاختبار المنظومة المتكاملة، لا نتوقّع أن نطلب استخدام خدمات المفاتيح/القيمة المفتوحة المصدر أو بيئة التنفيذ الموثوقة (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 سواء كنت مالكًا لموقع إلكتروني أو مستخدمًا فرديًا.

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

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

هناك سياستان لأذونات "الجمهور المحمي" يمكن ضبطهما بشكل مستقل:

تفعيل/إيقاف وظيفة "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>

يقدّم قسم سياسة الأذونات التجريبية لأذونات الاستخدام التجريبي المقترَحة المتعلّقة بأوّل شرائح جمهور محمية في Google مزيدًا من التفاصيل.

إيقاف مشاركة البيانات من جانب المستخدم

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

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

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

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

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

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

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

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

ستظهر أيضًا النصوص البرمجية المباشرة للعمل ضمن لوحة Threads.

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

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

تتبُّع أحداث Protected Audience

من لوحة التطبيق في "أدوات مطوري البرامج في Chrome"، يمكنك متابعة أحداث المزاد وفئات الاهتمام ضمن Protected Audience API.

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

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

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

لوحة تطبيق "أدوات مطوري البرامج" في Chrome Canary، تعرض معلومات عن عروض أسعار المزاد أمام Protected Audience API والأحداث الفائزة.

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

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

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

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

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

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

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

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

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

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

تطلب المنصّة جانب الطلب (أو المعلن نفسه) للمعلن 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 ضمن ميزة Protected Audience API لإيقاف مكالمات 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() من قِبل seller في المساحة الإعلانية. ويوفّر ذلك معلومات عن سياق الصفحة (مثل حجم الإعلان والرقم التعريفي للناشر) ونوع المزاد (السعر الأول أو السعر الثاني) وبيانات وصفية أخرى.
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/مسرد#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 Worklet الخاص بالمزاد.
`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. يُرجى الاطّلاع على قسم المشاركون في المزاد في الشرح التوضيحي بشأن Protected Audience للحصول على مزيد من المعلومات.

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

يجب أن يتضمّن الرمز في 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 يوفر قيمًا لكل مفتاح من المفاتيح.

نقطة رئيسية: في المرحلة التجريبية الأولية الحالية لاختبار Protected Audience، يجب أن يكون المصدر 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. لتتمكّن من اختبار الطرق، فعِّل جميع واجهات برمجة التطبيقات Ad Privacy API ضمن "chrome://settings/adPrivacy". إذا كنت تشغِّل Chrome باستخدام علامات سطر الأوامر لتفعيل Protected Audience، عليك تفعيل الطرق بشكل صريح من خلال تضمين علامة BiddingAndScoringDebugReportingAPI. إذا لم يكُن العلامة مفعّلة، ستظلّ الطرق متاحة ولكن ليس لها أيّ إجراء.

8. الإبلاغ عن نقرة على إعلان

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

يتم الإبلاغ عن نقرة على إعلان معروض في إطار محاط بسياج. لمزيدٍ من المعلومات عن كيفية عمل ذلك، اطّلع على إعداد تقارير إعلانات الإطارات الخاضعة لقيود.

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

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

ما الفرق بين Protected Audience وTURTLEDOVE؟

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لطرح سؤال حول عملية التنفيذ أو العرض التوضيحي أو المستندات:

فتح مشكلة جديدة في مستودع دعم Privacy-Sandbox-dev تأكَّد من اختيار نموذج المشكلة لميزة Protected Audience.
يمكنك طرح مشكلة في مستودع الرموز التجريبية على GitHub.
لمزيد من الأسئلة العامة حول كيفية تلبية حالات الاستخدام لواجهة برمجة التطبيقات، يمكنك الإبلاغ عن مشكلة في مستودع الاقتراح.

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

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

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

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

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

صورة من إعداد راي هينيسي على قناة Unقلاش.