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

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

إذا كنت لا تعرف الكثير عن Protected Audience API، يمكنك الاطّلاع على نظرة عامة على Protected Audience API للحصول على شرح تفصيلي لواجهة برمجة التطبيقات.

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

حالة التنفيذ

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

ما هي واجهة برمجة التطبيقات Protected Audience API؟

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

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

تجربة Protected Audience API

مرجع واجهة برمجة التطبيقات المتاح

يقدّم هذا المستند نظرة عامة على Protected Audience API. إذا كنت تبحث عن طرق ومَعلمات معيّنة لواجهة برمجة التطبيقات:

يمكنك أيضًا الاطّلاع على أفضل الممارسات المتعلّقة بوقت استجابة المزاد الإعلاني في Protected Audience API.

Protected Audience API demo

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

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

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

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

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

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

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

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

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

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

أدرِج العلامة BiddingAndScoringDebugReportingAPI لتفعيل methods reporting methods temporary debug loss/win.

الميزات المتاحة

إنّ 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. يُطلب من متصفّح المستخدِم إضافة مجموعة باهتمامات مشتركة.

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

يُطلِق وسيط عرض الطلب للمعلِن (أو المعلِن نفسه) طلبات إلى navigator.joinAdInterestGroup() لطلب إضافة مجموعة باهتمامات مشتركة إلى قائمة المجموعات التي ينتمي إليها المتصفّح.

في هذا المثال، اسم المجموعة هو custom-bikes، والمالك هو dsp.example. سيكون مالك المجموعة ذات الاهتمامات المشتركة (في هذه الحالة، وسيط عرض الطلب) مشترًا في مزاد الإعلانات في Protected Audience API. يخزِّن المتصفّح معلومات العضوية في المجموعات ذات الاهتمامات المشتركة على جهاز المستخدم، ولا تتم مشاركتها مع موفِّر المتصفّح أو أي شخص آخر.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
  • مصدر عنوان URL الأساسي هو trustedBiddingSignalsUrl.
  • يقدّم المتصفّح hostname.
  • يتم الحصول على قيمة keys من trustedBiddingSignalsKeys.

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

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

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

يتمّ حلّ الوعد الذي يعرضه runAdAuction() إلى كائن إعداد إطار محدود (FencedFrameConfig) عند ضبط العلامةresolveToConfig على true في إعدادات المزاد. يستخدم الإطار المحدود إعدادات الإطار للانتقال إلى الإطار الذي يعرض الإعلان الفائز، ولكن لا يظهر عنوان URL للإعلان لمُضمِّن الإطار.

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

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

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

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

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

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

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


نظرة عامة على كل مرحلة من مراحل مزاد الإعلانات في Protected Audience API
يوضّح هذا المخطّط البياني كل مرحلة من مراحل مزاد Protected Audience API.

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

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

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

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

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

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

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

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

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

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

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

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

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

إيقاف

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

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