دليل المطوِّر لمزادات الإعلانات على الجهاز فقط لعرض تجديد النشاط التسويقي وشرائح الجمهور المخصّصة بدون تتبُّع الجهات الخارجية على مواقع إلكترونية متعددة
بالنسبة إلى المستخدمين الجدد في Protected Audience API، يُرجى الاطّلاع على مقالة نظرة عامة على Protected Audience API. للحصول على شرح رفيع المستوى لواجهة برمجة التطبيقات.
تمت كتابة هذه المشاركة لمطوّري البرامج كمرجع فني لمعظم التكرار الأخير لواجهة Protected Audience API التجريبية عرض توضيحي تتوفّر ميزة نشر Protected Audience API فضلاً عن مراجع واجهة برمجة التطبيقات للمشترين والبائعين
حالة التنفيذ
- The Protected Audience API proposal is now moving to general availability. Raise questions and follow discussion.
- Protected Audience API status of pending capabilities details changes and enhancements to the Protected Audience API API and features.
- Blink status
- Protected Audience API Chrome platform status: Specific to the Protected Audience API on Chrome.
- Ads API Chrome platform status: A collection of APIs to facilitate advertising: Protected Audience API, Topics, Fenced Frames and Attribution Reporting.
To be notified of status changes in the API, join the mailing list for developers.
ما هي 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 على مستوى المعلِن والناشرين تتوفّر هذه المواقع على protected-audience-demo.web.app/.
اختبار واجهة برمجة التطبيقات هذه
يمكنك اختبار Protected Audience API على مستخدم واحد في الإصدار التجريبي 101.0.4951.26 من Chrome والإصدارات الأحدث على جهاز سطح المكتب:
- تفعيل جميع واجهات برمجة تطبيقات الخصوصية في عرض الإعلانات ضمن "
chrome://settings/adPrivacy" - ضبط العلامات من سطر الأوامر يمكن العثور على القائمة الكاملة لعلامات Protected Audience API المتاحة في البحث في رموز Chromium
عرض الإعلانات في إطارات 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. سيُطلَب من متصفّح المستخدم إضافة مجموعة اهتمامات.
يستدعي وسيط عرض الطلب (DSP) للمعلن (أو المعلن نفسه)
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. يتم إجراء مزاد إعلانات في المتصفح
من المحتمل أن تتم إدارة مزاد الإعلانات بواسطة مزوّد جهة العرض للناشر (SSP) أو الناشر نفسه. الغرض من المزاد هو اختيار الإعلان الأنسب لشريحة إعلانية واحدة متاحة في الصفحة الحالية. تشير رسالة الأشكال البيانية في الاعتبار مجموعات الاهتمامات التي ينتمي إليها المتصفّح إلى جانب بيانات المشترين والبائعين في المساحة الإعلانية خدمات المفتاح/القيمة:
- قراءة الشرح التوضيحي لواجهة برمجة التطبيقات 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. لمزيد من المعلومات حول الكائن 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 من NextRoll ألبوم PARRROT لشركة Magnite الأدوار المختلفة التي كان يلعبها المشترين والبائعون المزاد على الجهاز فقط. يستند مسار عروض أسعار الإعلانات أو النتائج في Protected Audience API إلى هذه العوامل.
- مستند إلى النتائج من عرض RTB House وعلى مستوى المنتج ساهمت تعديلات TURTLEDOVE في تحسين نموذج إخفاء الهوية والتخصيص إمكانات المزاد على الجهاز فقط
- 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؟
التخزين المؤقت للموارد التي تحتوي على أدوات Protected Audience API يمكنك استخدام العنوان Cache-Control للتحكّم في سلوك التخزين المؤقت.
التفاعل مع الملاحظات ومشاركتها
الحصول على الدعم
لطرح أسئلة والحصول على الدعم بشأن عملية التنفيذ أو العرض التوضيحي التوثيق:
- GitHub: اطّلِع على موضح، طرح الأسئلة ومتابعة المناقشة
- العرض التوضيحي: يمكنك طرح مشكلة في مستودع الرموز التجريبية.
- فريق دعم المطوّرين: يمكنك طرح الأسئلة والانضمام إلى المناقشات على دعم مطوّري برامج "مبادرة حماية الخصوصية" المستودع. اختَر نموذج المشكلة في Protected Audience API.
- تنفيذ Chrome: للأخطاء أو المشكلات المتعلقة بتنفيذ Chrome Protected Audience API، يمكنك الاطّلاع على المشاكل الحالية أو إبراز مشكلة جديدة
إذا أردت طرح المزيد من الأسئلة العامة حول تلبية احتياجاتك باستخدام Protected Audience API، يُرجى اتّباع الخطوات التالية: الإبلاغ عن مشكلة في مستودع واجهة برمجة التطبيقات. يمكنك أيضًا مناقشة حالات الاستخدام المتّبَعة في المجال في تحسين مجموعة أعمال الإعلان على الويب.
استخدام نموذج الملاحظات والآراء حول "مبادرة حماية الخصوصية" لمشاركة الملاحظات بشكل خاص مع فريق Chrome خارج المنتديات العامة.
إيقاف
هل تريد إيقاف Protected Audience API؟ تعرَّف على كيفية حظر الوصول إلى Protected Audience API كمالك للموقع أو مستخدم فردي.
البقاء على اطّلاع
- لتلقّي إشعارات بتغييرات حالة واجهة برمجة التطبيقات، يمكنك الانضمام إلى للمطوّرين.
- لمتابعة كل المناقشات الجارية حول واجهة برمجة التطبيقات عن كثب، انقر على الزر مشاهدة في صفحة واجهة برمجة التطبيقات على GitHub. يتطلب ذلك أن يكون لديك أو إنشاء موقع GitHub الحساب.
- لتلقّي آخر الأخبار العامة حول "مبادرة حماية الخصوصية"، يُرجى الاشتراك في خلاصة RSS. [التقدّم في "مبادرة حماية الخصوصية"]:
- الانضمام إلى الطلبات المجدوَلة لواجهة Protected Audience API (كل أسبوع ثانٍ). يمكن للجميع الانضمام إلى هذه الفعالية والمشاركة فيها احرص أولاً على الانضمام إلى WICG. إِنْتَ المشاركة بنشاط أو الاستماع فقط!