دليل المطوِّر لمزادات الإعلانات على الجهاز فقط لعرض قوائم تجديد النشاط التسويقي وشرائح الجمهور المخصّصة بدون تتبُّع الجهات الخارجية على مواقع إلكترونية متعددة
بالنسبة إلى المستخدمين الجدد الذين يستخدمون Protected Audience API، يُرجى الاطّلاع على مقالة نظرة عامة حول Protected Audience API للحصول على شرح مفصَّل.
تمّت كتابة هذه المشاركة للمطوّرين كمرجع فني لأحدث تكرار من Protected Audience API التجريبية. يتوفّر عرض توضيحي حول عملية نشر Protected Audience API الأساسية، بالإضافة إلى مراجع واجهة برمجة التطبيقات للمشترين والبائعين.
حالة التنفيذ
- يتمّ الآن نقل اقتراح Protected Audience API إلى مدى التوفّر للجمهور العام. طرح الأسئلة ومتابعة المناقشة:
- توضّح حالة Protected Audience API للإمكانات في انتظار المراجعة التغييرات والتحسينات التي طرأت على Protected Audience API وميزاتها.
- حالة وميض
- حالة نظام Chrome الأساسي في Protected Audience API: تنطبق على Protected Audience API على Chrome.
- حالة منصّة Chrome لـ Ads API: مجموعة من واجهات برمجة التطبيقات لتسهيل عرض الإعلانات: Protected Audience API وTopics وFenced Frames (الإطارات المسوّرة) وتقارير تحديد المصدر.
لتلقّي إشعارات بشأن تغييرات الحالة في واجهة برمجة التطبيقات، يمكنك الانضمام إلى القائمة البريدية لمطوّري البرامج.
ما هي Protected Audience API؟
Protected Audience API هي واجهة برمجة تطبيقات في مبادرة حماية الخصوصية تمّ تصميمها لعرض حالات استخدام تجديد النشاط التسويقي والجمهور المخصّص كي لا تستخدمها الجهات الخارجية لتتبُّع سلوك تصفُّح المستخدمين على المواقع الإلكترونية. تتيح واجهة برمجة التطبيقات إمكانية إجراء مزادات على الجهاز فقط من خلال المتصفّح، واختيار الإعلانات الملائمة للمواقع الإلكترونية التي زارها المستخدم من قبل.
Protected Audience API هي أوّل تجربة يتم تنفيذها في Chromium ضمن مجموعة الاقتراحات TURTLEDOVE.
تجربة Protected Audience API
مرجع واجهة برمجة التطبيقات المتاح
يقدّم هذا المستند نظرة عامة على Protected Audience API. إذا كنت تبحث عن طُرق ومَعلمات محدَّدة لواجهة برمجة التطبيقات:
- دليل المشترين
joinAdInterestGroup()وgenerateBid() - دليل البائع لـ Protected Audience API
runAdAuction() - دليل المشترين إلى
reportWin()ودليل البائعين إلىreportResult() - تحديد المشاكل في Protected Audience API وحلّها
ويمكنك أيضًا الاطّلاع على أفضل الممارسات المتعلقة بوقت استجابة مزاد الإعلانات في Protected Audience API.
عرض توضيحي لواجهة برمجة التطبيقات Protected Audience API
تتوفّر إرشادات مفصَّلة حول عملية نشر Protected Audience API الأساسية على المواقع الإلكترونية للمعلِنين والناشرين على الرابط Protect-audience-demo.web.app/.
الاختبار باستخدام علامة chrome://flags أو علامات الميزات
يمكنك اختبار Protected Audience API لمستخدم واحد في الإصدار التجريبي 101.0.4951.26 أو الإصدارات الأحدث من Chrome على الكمبيوتر المكتبي باتّباع الخطوات التالية:
- تفعيل "
chrome://flags/#privacy-sandbox-ads-apis" - يمكنك تحديد العلامات من سطر الأوامر. يمكن العثور على القائمة الكاملة لعلامات Protected Audience API المتوفّرة في أداة Chromium Code Search.
عرض الإعلانات في إطارات iframe أو إطارات مضمّنة
يمكن عرض الإعلانات في <iframe> أو <fencedframe>، بناءً على العلامات التي تم ضبطها.
لاستخدام <fencedframe> لعرض الإعلانات، اتّبِع الخطوات التالية:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames
لاستخدام <iframe> لعرض الإعلانات، اتّبِع الخطوات التالية:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames
ضمِّن العلامة BiddingAndScoringDebugReportingAPI لتفعيل الطرق المؤقتة لإعداد تقارير الخسارة/الفوز وتصحيح الأخطاء.
الميزات المتاحة
إنّ Protected Audience API المستندة إلى ميزة الإبلاغ عن الميزات في Chromium هي تجربة أولى لاختبار الميزات التالية Protected Audience API:
- مجموعات الاهتمامات: يخزّنها المتصفّح مع البيانات الوصفية المرتبطة بها لضبط عروض أسعار الإعلانات وعرضها.
- عروض الأسعار على الجهاز فقط حسب المشترين (DSP أو المعلِن): استنادًا إلى مجموعات الاهتمامات والإشارات المخزَّنة من البائع.
- اختيار البائع للإعلانات على الجهاز فقط (SSP أو الناشر): استنادًا إلى عروض أسعار المزاد والبيانات الوصفية من المشترين
- عرض الإعلانات في نسخة مريحة مؤقتة من الإطارات Fenced Frames: مع السماح بالوصول إلى الشبكة والتسجيل لعرض الإعلانات
يمكنك الاطّلاع على مزيد من المعلومات حول إتاحة الميزات والقيود المفروضة عليها في الشرح التوضيحي Protected Audience API.
أذونات مجموعة الاهتمامات
إنّ الإعداد التلقائي للتنفيذ الحالي لـ Protected Audience API هو السماح باستدعاء واجهة
joinAdInterestGroup()
من أي مكان في الصفحة، حتى من إطارات iframe في جميع النطاقات.
في المستقبل، عندما يتوفّر لمالكي المواقع الإلكترونية الوقت لتعديل سياسات أذونات إطارات iframe في جميع النطاقات، ستكون الخطة هي منع الطلبات الواردة من إطارات iframe عبر النطاقات.
خدمة المفتاح/القيمة
لإتاحة مزاد إعلانات Protected Audience API، يمكن للمتصفّح الوصول إلى خدمة المفتاح/القيمة لاسترداد المعلومات في الوقت الفعلي التي تتوافق مع مزاد الإعلانات في Protected Audience API. يمكن استخدام هذه المعلومات بعدة طرق:
- قد يرغب المشترون في حساب الميزانية المتبقية في حملة إعلانية.
- قد يُطلب من البائعين التحقّق من توافق تصاميم الإعلانات مع سياسات الناشر.
أصبح رمز خدمة/قيمة Protected Audience API متاحًا الآن. يمكنك مراجعة مشاركة مدونة الإعلان لمعرفة معلومات عن تحديث الحالة.
لأغراض الاختبار الأولي، تم تقديم نموذج "إحضار خادمك". على المدى الطويل، ستحتاج تقنيات الإعلانات إلى استخدام خدمات المفاتيح/القيمة المفتوحة المصدر Protected Audience API التي تعمل في بيئات تنفيذ موثوقة.
يُرجى الرجوع إلى مشاركة المدوّنة حول خدمات Protected Audience API للاطّلاع على آخر الأخبار حول المخطط الزمني وسنقدم إشعارًا مهمًا للمطورين لبدء الاختبار والاعتماد قبل تنفيذ هذا الانتقال.
اكتشاف دعم الميزات
قبل استخدام واجهة برمجة التطبيقات، تحقق مما إذا كانت متوافقة مع المتصفح ومتاحة في المستند:
'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 API؟
في هذا المثال، يتصفح أحد المستخدمين الموقع الإلكتروني لصانع دراجة مخصص، ثم يزور لاحقًا موقعًا إخباريًا على الويب ويظهر في وقت لاحق إعلانًا لدراجة جديدة من صانع الدراجة.
وستتم إضافة ميزات Protected Audience API بمرور الوقت بينما نعمل على تطويرها.
1- يزور أحد المستخدِمين أحد المواقع الإلكترونية لأحد المعلِنين.
تخيل أن مستخدمًا يزور الموقع الإلكتروني لصانع دراجة مخصص (المعلِن) في هذا المثال) ويقضي بعض الوقت على صفحة المنتج لدراجة فولاذية مصنوعة يدويًا. يوفر هذا لصانع الدراجة فرصة تجديد النشاط التسويقي.
2- يُطلب من متصفّح المستخدم إضافة مجموعة اهتمامات.
تطلب منصة المعلن على جانب الطلب (أو المعلن نفسه)
navigator.joinAdInterestGroup() لتطلب من المتصفّح إضافة مجموعة اهتمامات إلى قائمة المجموعات التي ينتمي إليها المتصفّح.
في هذا المثال، تُسمى المجموعة custom-bikes والمالك هو dsp.example. سيكون مالك مجموعة الاهتمامات (في هذه الحالة، وسيط عرض الطلب) مشتريًا في مزاد إعلانات Protected Audience API. يخزّن المتصفح أو على جهاز المستخدم عضوية مجموعة الاهتمامات، ولا تتم مشاركتها مع مورّد المتصفّح أو أي جهة أخرى.
- قراءة الرسالة التوضيحية Protected Audience API: مجموعات الاهتمامات في سجلّات المتصفِّحات
- قراءة دليل واجهة برمجة التطبيقات: المشترون ومقدّمو الخدمات الرقمية (DSP)، وتعرَّف على كيفية
joinAdInterestGroup()وإنشاء عروض الأسعار.
تحديد إعلانات لمجموعة اهتمامات
يتضمّن عنصرا ads وadComponents عنوان URL لتصميم الإعلان،
وبيانات وصفية عشوائية يمكن استخدامها في وقت تقديم عروض الأسعار اختياريًا. مثال:
{
renderUrl: 'https://cdn.example/.../bikeAd1.html',
metadata: bikeAd1metadata // optional
}
كيف يقدّم المشترون عروض الأسعار؟
يتم استدعاء generateBid() لكل مجموعة اهتمام يكون المتصفّح عضوًا فيها، في حال دعوة مالك المجموعة ذات الاهتمامات المشتركة لتقديم عرض سعر.
اطّلِع على مستندات مطوّري برامج "generatedBid()".
3. زيارة المستخدم لموقع إلكتروني يبيع مساحة إعلانية
وفي وقت لاحق، يزور المستخدِم موقعًا إلكترونيًا يبيع مساحة إعلانية، في هذا المثال موقع إلكتروني إخباري. يحتوي الموقع على مستودع إعلانات يبيعه آليًا باستخدام عروض الأسعار في الوقت الفعلي.
4- يتم إجراء مزاد إعلانات في المتصفح
من المرجَّح أن يتم إجراء مزاد الإعلانات من قِبل موفّر جهة المورّد لدى الناشر أو الناشر نفسه. الغرض من المزاد هو اختيار الإعلان الأنسب لشريحة إعلانية واحدة متاحة على الصفحة الحالية. يأخذ المزاد في الاعتبار مجموعات الاهتمامات التي ينتمي إليها المتصفّح، إلى جانب بيانات من المشترين في المساحات الإعلانية والبائعين من خدمات المفاتيح/القيمة.
- قراءة الرسالة التوضيحية Protected Audience API: يجري البائعون مزادات على الأجهزة
- قراءة دليل واجهة برمجة التطبيقات: يمكن للبائعين الاطّلاع على مزيد من المعلومات عن
runAdAuction()وأفضل الممارسات لوقت استجابة مزاد الإعلانات.
5- يطلب البائع والمشترين المشاركون بيانات في الوقت الفعلي من خدمة المفتاح/القيمة.
خلال مزاد الإعلانات، يمكن للبائع طلب بيانات في الوقت الفعلي حول مواد إبداعية معيَّنة من خلال تقديم طلب إلى خدمة المفتاح/القيمة.
يمكن للبائع طلب هذه المعلومات خلال runAdAuction() من خلال السمة trustedScoringSignalsUrl، بالإضافة إلى المفاتيح من السمات 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 API: جلب البيانات في الوقت الفعلي من خدمة القيمة/مفتاح واجهة برمجة التطبيقات Protected Audience API
- اطّلِع على مقالة فتح مصدر مفتاح/قيمة واجهة برمجة التطبيقات Protected Audience API.
6- يتم عرض الإعلان الفائز.
يتم تحويل الوعد الذي يعرضه runAdAuction() إلى عنصر إعدادات إطار مضمّن مستقل (FencedFrameConfig) عند ضبط العلامةresolveToConfig على true في إعدادات المزاد. يتم استخدام تهيئة الإطار بواسطة إطار مضمّن لنقل الإطار إلى الإعلان الفائز، غير أن عنوان URL للإعلان لا يظهر للأداة المضمَّنة في الإطار.
يتوفّر عنصر ضبط الإطار المسموح له باستخدام الإصدار M114 بدءًا من الإصدار M114. لمزيد من المعلومات حول الكائن FencedFrameConfig، يُرجى الاطّلاع على مقالة مدونة Chrome.
- قراءة الرسالة التوضيحية Protected Audience API: تعرض المتصفّحات الإعلان الفائز.
7- يتم الإبلاغ عن نتيجة المزاد
تتمثل الخطة طويلة الأجل في السماح للمتصفّح بالإبلاغ عن نتائج المزاد للبائع والمشترين باستخدام واجهات برمجة التطبيقات الخاصة للتجميع الخاص.
كآلية إعداد تقارير مؤقتة على مستوى الحدث، يمكن للرمز الذي ينفّذ
reportResult() للبائع والرمز reportWin() لمقدّم عروض الأسعار الفائز استدعاء الدالة sendReportTo(). ويستعين هذا بوسيطة واحدة: سلسلة تمثِّل عنوان URL الذي يتم جلبه بعد اكتمال المزاد، والتي تشفّر المعلومات على مستوى الحدث المطلوب الإبلاغ عنها.
- اقرأ دليل واجهة برمجة التطبيقات: تعرَّف على إعداد تقارير البائعين والمشترين
8- يتم الإبلاغ عن نقرة على إعلان
يتم الإبلاغ عن نقرة على إعلان يتم عرضه في إطار مضمّن. للاطّلاع على مزيد من المعلومات عن طريقة تنفيذ ذلك، اطّلِع على إعداد تقارير حول إعلانات الإطارات المضمّنة.
ما الفرق بين Protected Audience API وTURTLEDOVE؟
Protected Audience API هي أوّل تجربة يتم تنفيذها في Chromium ضمن مجموعة اقتراحات TURTLEDOVE.
تتّبع Protected Audience API مبادئ TURTLEDOVE العالية المستوى. استندت بعض الإعلانات عبر الإنترنت إلى عرض إعلان على شخص يُحتمل أن يكون مهتمًا به سبق له التفاعل مع المعلن أو شبكة المواقع الإعلانية. في السابق، تمكّن المعلِن من التعرّف على شخص معيّن أثناء تصفحه للمواقع الإلكترونية، وهي مشكلة أساسية متعلّقة بالخصوصية في عالم الويب اليوم.
تتمحور مبادرة TURTLEDOVE حول توفير واجهة برمجة تطبيقات جديدة لمعالجة حالة الاستخدام هذه مع تقديم بعض التطورات الرئيسية في الخصوصية:
- أما المتصفح، وليس المعلن، فهو يحتفظ بالمعلومات المتعلقة بما يعتقد المعلن أنه يهتم به.
- يمكن للمعلنين عرض الإعلانات استنادًا إلى أحد الاهتمامات، ولكن لا يمكنهم الجمع بين هذا الاهتمام والمعلومات الأخرى عن شخص، وبشكل خاص، عن هويته، أو الصفحة التي يزورها.
نشأ Protected Audience API من TURTLEDOVE ومجموعة من الاقتراحات ذات الصلة بالتعديلات بهدف تقديم خدمة أفضل للمطوّرين الذين سيستخدمون واجهة برمجة التطبيقات:
- في SPARROW: اقترح Criteo إضافة نموذج خدمة ("Gatekeeper") يعمل في بيئة تنفيذ موثوق بها (TEE). تشمل Protected Audience API استخدامًا محدودًا بشكل أكبر لواجهات برمجة التطبيقات (TEE) من أجل البحث عن البيانات في الوقت الفعلي وإعداد التقارير المجمَّعة.
- وصفت اقتراحات TERN وPARRROT من NextRoll الأدوار المختلفة للمشترين والبائعين في المزاد على الجهاز فقط. ويستند مسار عروض أسعار أو نتائج الإعلانات في Protected Audience API إلى هذا العمل.
- تم تحسين إمكانات التخصيص ونموذج إخفاء الهوية في المزاد على الجهاز فقط بفضل التعديلات المستندة إلى النتائج وعلى مستوى المنتج في RTB House
- PARAKEET هي اقتراح من Microsoft لخدمة إعلانية شبيهة بـ TURTLEDOVE تعتمد على خادم وكيل يعمل على بيئة التنفيذ الموثوقة (TEE) بين المتصفح ومزوّدي تقنية الإعلان، وذلك لإخفاء هوية طلبات الإعلان وفرض خصائص الخصوصية. لم تستخدِم Protected Audience API نموذج الخادم الوكيل هذا. نحن بصدد دمج واجهات برمجة تطبيقات JavaScript لـ PARAKEET وProtected Audience API، لدعم العمل المستقبلي لدمج أفضل ميزات كلا الاقتراحين.
لم تمنع بعد Protected Audience API شبكة المواقع الإعلانية الخاصة بالمواقع الإلكترونية من التعرّف على الإعلانات التي يراها المستخدم. نتوقع تعديل واجهة برمجة التطبيقات لتصبح أكثر خصوصية بمرور الوقت.
هل يمكن استخدام Topics API مع Protected Audience API؟
نعم. موضوع يتم تتبّعه وتابع للمستخدم الحالي بواسطة Topics API. ويمكن استخدامه كمعلومات سياقية من قِبل البائع أو مقدّم عروض الأسعار. يمكن تضمين موضوع في السمات التالية:
auctionSignals، وهي خاصية لعنصر إعداد المزاد الذي تم تمريره إلىnavigator.runAdAuction()userBiddingSignals، وهي خاصية لكائن إعداد مجموعة الاهتمامات تم تمريرها إلىnavigator.joinAdInterestGroup()
إعدادات المتصفِّح المتاحة
يمكن للمستخدمين تعديل مشاركتهم في الفترات التجريبية من "مبادرة حماية الخصوصية" في Chrome من خلال
تفعيل إعداد المستوى الأعلى أو إيقافه في
chrome://settings/adPrivacy.
أثناء الاختبار الأوّلي، سيتمكّن المستخدمون من استخدام إعداد "مبادرة حماية الخصوصية" العالي المستوى لإيقاف Protected Audience API. يخطط Chrome للسماح للمستخدمين برؤية وإدارة قائمة المجموعات ذات الاهتمامات المشتركة التي تمت إضافتهم إليها عبر مواقع الويب التي زاروها. كما هو الحال مع تقنيات "مبادرة حماية الخصوصية" نفسها، قد يتم تطوير إعدادات المستخدمين بالاستناد إلى ملاحظات المستخدمين والهيئات التنظيمية وغيرهم.
سنواصل تعديل الإعدادات المتاحة في Chrome بناءً على الاختبارات والملاحظات. ونخطّط في المستقبل لتوفير إعدادات أكثر دقة لإدارة Protected Audience API والبيانات المرتبطة بها.
لا يمكن لمتصلي واجهة برمجة التطبيقات الوصول إلى الانتساب في المجموعة عند تصفُّح المستخدمين في "وضع التصفّح المتخفي"، وتتمّ إزالة الاشتراك عندما يمحو المستخدمون بيانات الموقع الإلكتروني.
هل يخزّن المتصفِّح وظائف "الجمهور المحمي" الصغيرة؟
يُخزن المتصفّح مؤقتًا الموارد التي تحتوي على وظائف Protected Audience الرئيسية، وهي الوظائف المصغّرة لإنشاء عروض الأسعار وإعداد التقارير والخاصة بالمشتري، ومجموعات بيانات نتائج الإعلانات وإعداد التقارير لدى البائع. يمكنك استخدام عنوان Cache-Control للتحكّم في سلوك التخزين المؤقت.
التفاعل ومشاركة الملاحظات
الحصول على الدعم
لطرح أسئلة والحصول على الدعم بشأن عملية التنفيذ أو العرض التوضيحي أو الوثائق:
- GitHub: يمكنك قراءة الشرح وطرح الأسئلة ومتابعة المناقشة.
- عرض توضيحي: يمكنك طرح مشكلة في مستودع الرموز التجريبية.
- دعم المطوّرين: يمكنك طرح الأسئلة والانضمام إلى المناقشات في مستودع دعم المطوّرين في "مبادرة حماية الخصوصية". اختَر نموذج المشكلة في Protected Audience API.
- تنفيذ Chrome: عند رصد أخطاء أو مشاكل في تنفيذ Chrome لـ Protected Audience API، يمكنك الاطّلاع على المشاكل الحالية أو طرح مشكلة جديدة.
لمزيد من الأسئلة العامة حول تلبية احتياجاتك باستخدام Protected Audience API، يمكنك الإبلاغ عن مشكلة في مستودع واجهة برمجة التطبيقات. يمكنك أيضًا مناقشة حالات الاستخدام في هذا المجال من خلال الانتقال إلى مجموعة أعمال تحسين الإعلانات على الويب التابعة لـ W3C.
استخدِم نموذج الملاحظات الخاص بـ "مبادرة حماية الخصوصية" لمشاركة الملاحظات بشكل خاص مع فريق Chrome خارج المنتديات العامة.
إيقاف
هل تريد إيقاف Protected Audience API؟ تعرَّف على كيفية حظر الوصول إلى Protected Audience API بصفتك مالك موقع إلكتروني أو مستخدِم فردي.
البقاء على اطّلاع
- لتلقّي إشعارات بالتغييرات في حالة واجهة برمجة التطبيقات، انضم إلى القائمة البريدية للمطوّرين.
- لمتابعة جميع المناقشات الجارية حول واجهة برمجة التطبيقات عن كثب، انقر على الزر مشاهدة في صفحة واجهة برمجة التطبيقات على GitHub. يتطلب ذلك أن يكون لديك أو حساب GitHub.
- للاطّلاع على آخر الأخبار العامة حول "مبادرة حماية الخصوصية"، يُرجى الاشتراك في خلاصة RSS [التقدّم في مبادرة حماية الخصوصية].
- الانضمام إلى الطلبات المُجدوَلة في Protected Audience API (كل أسبوع) نرحّب بالجميع للانضمام - للمشاركة، تأكد أولاً من الانضمام إلى WICG. يمكنك المشاركة بنشاط أو مجرد الاستماع!