Protected Audience API: دليل المطوّرين

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

بالنسبة إلى المستخدمين الجُدد في 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 على Chrome.
• حالة منصة Ads API Chrome: مجموعة من واجهات برمجة التطبيقات لتسهيل عرض الإعلانات، وهي: Protected Audience API وTopics وFenced Frames وAttribution Reporting.

لتلقّي إشعارات بشأن التغييرات في حالة واجهة برمجة التطبيقات، انضم إلى القائمة البريدية الخاصة بالمطوّرين.

ما هي واجهة 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 لمستخدم واحد في الإصدار التجريبي من Chrome 101.0.4951.26 والإصدارات الأحدث على أجهزة الكمبيوتر المكتبي باتّباع الخطوات التالية:

• فعِّل جميع واجهات برمجة التطبيقات الخاصة بالخصوصية في عرض الإعلانات ضِمن chrome://settings/adPrivacy.
• ضبط العلامات من سطر الأوامر يمكن الاطّلاع على القائمة الكاملة بعلامات 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:

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

يمكنك الاطّلاع على مزيد من المعلومات حول توافق الميزات والقيود في شرح 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: المتصفّحات تسجّل مجموعات الاهتمامات
• قراءة دليل واجهة برمجة التطبيقات: يمكن للمشترين ومنصّات عرض الطلب التعرّف على كيفية joinAdInterestGroup() وإنشاء عروض أسعار.

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

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

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

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

يتم استدعاء generateBid() لكل مجموعة اهتمامات يكون المتصفّح عضوًا فيها، وذلك إذا تمت دعوة مالك المجموعة ذات الاهتمامات المشتركة لتقديم عروض أسعار.

اطّلِع على generatedBid() مستندات المطوّرين.

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

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

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

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

• قراءة شرح Protected Audience API: البائعون يجرون مزادات على الجهاز
• قراءة دليل واجهة برمجة التطبيقات: يمكن للبائعين الاطّلاع على مزيد من المعلومات حول runAdAuction() وأفضل الممارسات المتعلقة بوقت استجابة مزاد الإعلانات.

5- يطلب البائع والمشترون المشاركون بيانات في الوقت الفعلي من خدمة Key/Value

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

يتوفّر عنصر إعدادات الإطار المحصور بدءًا من الإصدار 114 من Chrome. لمزيد من المعلومات عن العنصر FencedFrameConfig، يُرجى الاطّلاع على مقالة مدونة Chrome.

• قراءة شرح Protected Audience API: المتصفّحات تعرض الإعلان الفائز

7. يتم تسجيل نتيجة المزاد

تتمثّل الخطة طويلة الأمد في السماح للمتصفّح بإعداد تقارير عن نتائج المزاد للبائعين والمشترين باستخدام واجهات Private Aggregation API.

بصفتها آلية مؤقتة لإعداد التقارير على مستوى الحدث، يمكن للرمز الذي ينفّذ 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 إضافة نموذج خدمة ("مراقب البوابة") يعمل في بيئة تنفيذ موثوقة (TEE). تتضمّن Protected Audience API استخدامًا أكثر محدودية لبيئات التنفيذ الموثوقة، وذلك للبحث عن البيانات في الوقت الفعلي وإعداد التقارير المجمَّعة.
• تضمّنت اقتراحات TERN من NextRoll وPARRROT من Magnite وصفًا للأدوار المختلفة التي يؤديها المشترون والبائعون في المزاد على الجهاز. يستند مسار عروض الأسعار/تسجيل النقاط في 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.

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

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

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

هل يخزّن المتصفّح worklet في Protected Audience مؤقتًا؟

يخزّن المتصفّح مؤقتًا الموارد التي تحتوي على عمليّات Protected Audience الصغيرة، أي عمليّات إنشاء عروض الأسعار وإعداد التقارير الخاصة بالمشتري، وعمليّات تسجيل نقاط الإعلانات وإعداد التقارير الخاصة بالبائع. يمكنك استخدام عنوان Cache-Control للتحكّم في سلوك التخزين المؤقت.

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

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

لطرح أسئلة والحصول على الدعم بشأن عملية التنفيذ أو العرض التوضيحي أو المستندات، اتّبِع الخطوات التالية:

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

للحصول على إجابات عن أسئلة أكثر عمومية حول تلبية احتياجاتك باستخدام Protected Audience API، يمكنك تقديم مشكلة في مستودع API. يمكنك أيضًا مناقشة حالات الاستخدام في المجال ضمن فريق تحسين أعمال الإعلان على الويب التابع لاتحاد شبكة الويب العالمية (W3C).

يمكنك استخدام نموذج الملاحظات الخاص بـ "مبادرة حماية الخصوصية" لمشاركة ملاحظاتك بشكل خاص مع فريق Chrome خارج المنتديات العامة.

إيقاف

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

تلقي آخر الأخبار

• للحصول على إشعارات بشأن التغييرات في حالة واجهة برمجة التطبيقات، انضم إلى القائمة البريدية للمطوّرين.
• لمتابعة جميع المناقشات الجارية حول واجهة برمجة التطبيقات عن كثب، انقر على الزر متابعة في صفحة واجهة برمجة التطبيقات على GitHub. يتطلّب ذلك أن يكون لديك حساب على GitHub أو أن تنشئ حسابًا.
• للحصول على آخر الأخبار حول "مبادرة حماية الخصوصية"، اشترِك في خلاصة RSS [التقدّم في "مبادرة حماية الخصوصية"].
• الانضمام إلى المكالمات المجدوَلة بشأن Protected Audience API(كل أسبوعين) يمكن للجميع الانضمام إلى المجموعة، ولكن للمشاركة، يجب أولاً الانضمام إلى WICG. يمكنك المشاركة بفاعلية أو الاستماع فقط.