تعريف بيانات الجمهور

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

ألست من المطوّرين؟ يُرجى الرجوع إلى نظرة عامة على Protected Audience API.

مجموعات الاهتمامات في Protected Audience API

تمثِّل مجموعة الاهتمامات في Protected Audience API مجموعة من المستخدِمين ذوي الاهتمامات المشتركة بما يتوافق مع قائمة تجديد النشاط التسويقي. لكل مجموعة اهتمامات في Protected Audience API مالك.

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

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

joinAdInterestGroup()

نظام وسيط الطلب الذي يستخدمه المعلن (DSP) أو يتصل المعلن نفسه بـ navigator.joinAdInterestGroup() ليطلب من المتصفّح إضافة مجموعة اهتمامات إلى قائمة عضوية المتصفّح.

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

يتطلّب "joinAdInterestGroup()" الحصول على إذن من:

يعني ذلك أنّه من غير الممكن أن يتصل "malicious.example" بـ "joinAdInterestGroup()" لمجموعة اهتمامات مملوكة من قِبل "dsp.example.com"، بدون منح "dsp.example.com" الإذن.

إذن من الموقع الإلكتروني الذي تمت زيارته

يمكن منح الإذن من المصدر نفسه أو من مصادر متعددة. يتم تلقائيًا منح الإذن لمكالمات joinAdInterestGroup() من المصدر نفسه الذي تمت زيارته للموقع الإلكتروني (بمعنى آخر، من المصدر نفسه الذي تم استخدامه في إطار المستوى الأعلى للصفحة الحالية).

مثال للاستخدام

في ما يلي مثال على كيفية تعريف مجموعة ذات اهتمام وطلب من المتصفِّح الانضمام إليها.

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  updateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

يجب ألا يزيد حجم عنصر interestGroup الذي يتم تمريره إلى الدالة عن 50 كيبيبايت، وإلّا لن تنجح عملية الاستدعاء. وتحدِّد المعلمة الثانية مدة المجموعة ذات الاهتمامات المشتركة، مع تحديد 30 يومًا كحد أقصى. تحلّ المكالمات المتتالية محلّ القيم المخزَّنة سابقًا.

السمات المطلوبة

السمات الوحيدة المطلوبة لمجموعات الاهتمامات هي owner وname:

الموقع مثال Role
owner https://dsp.example مصدر مالك مجموعة الاهتمامات.
name custom-bikes اسم مجموعة الاهتمامات.

السمات الاختيارية

أما المواقع المتبقية، فهي اختيارية:

biddingLogicUrl1، 2
مثال: https://dsp.example/bid/custom-bikes/bid.js
الدور: عنوان URL لعرض الأسعار الذي يتم تشغيله في JavaScript في Worklet
biddingWasmHelperUrl1، 2
مثال: https://dsp.example/bid/custom-bikes/bid.wasm
الدور: عنوان URL لرمز WebAssembly المستنِد إلى biddingLogicUrl.
updateUrl2
مثال: https://dsp.example/bid/custom-bikes/update
الدور: عنوان URL الذي يعرض تنسيق JSON لتعديل سمات مجموعة الاهتمامات. (اطّلِع على تعديل بيانات الجمهور وإعادة تحميل الإعلانات.)
trustedBiddingSignalsUrl2
مثال: https://dsp.example/trusted/bidding-signals
الدور: عنوان URL الأساسي لطلبات قِيَم المفاتيح في خدمة المفتاح/القيمة الموثوق بها التي يقدّمها مقدّم عروض الأسعار.
trustedBiddingSignalsKeys
مثال: ['key1', 'key2' ...]
الدور: مفاتيح الطلبات التي تخصّ خدمة المفتاح/القيمة الموثوق بها ذات القيمة الأساسية.
userBiddingSignals
مثال: {...}
الدور: البيانات الوصفية الإضافية التي يمكن للمالك استخدامها أثناء تقديم عروض الأسعار.
ads1
مثال: [bikeAd1, bikeAd2, bikeAd3]
الدور: الإعلانات التي يمكن عرضها لمجموعة الاهتمامات هذه.
adComponents
مثال: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]
الدور: مكوّنات الإعلانات المؤلفة من عدة أجزاء.

1 السمتان biddingLogicUrl وads اختياريتان، ولكنهما مطلوبتان للمشاركة في مزاد. قد تكون هناك حالات استخدام لإنشاء مجموعة اهتمامات بدون هذه الخصائص: على سبيل المثال، قد يرغب مالك مجموعة الاهتمامات في إضافة متصفّح إلى مجموعة اهتمام لحملة لم يتم تشغيلها بعد، أو لبعض الاستخدامات الأخرى في المستقبل، أو ربما نفدت ميزانيته الإعلانية مؤقتًا.

2 في التطبيق الحالي لواجهة Protected Audience API، يجب أن يكون لدى biddingLogicUrl وbiddingWasmHelperUrl وupdateUrl وtrustedBiddingSignalsUrl المصدر نفسه الخاص بالمالك. قد لا يكون ذلك قيدًا طويل الأمد، ولا يتضمّن عنوانا URL ads وadComponents هذا القيد.

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

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

مثال:

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

leaveAdInterestGroup()

يمكن لمالك مجموعة الاهتمامات طلب إزالة متصفِّح من مجموعة اهتمام. يزيل المتصفح مجموعة الاهتمامات من قائمة عضويته.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

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

يمكن أيضًا أن تستدعي رمز الإعلان هذه الدالة لمجموعة الاهتمامات المرتبطة به.

الأسئلة الشائعة

ما الحد الأقصى لعدد مجموعات الاهتمامات لكل مالك مجموعة لمستخدم واحد؟

يسمح Chrome بما يصل إلى 1,000 مجموعة اهتمام لكل مالك، وما يصل إلى 1,000 مالك للمجموعة ذات الاهتمامات المشتركة. تهدف هذه الحدود إلى وجود حواجز للحماية، ولا يمكن تجاوزها أثناء التشغيل المنتظم.

كيف يمكنني زيادة الإعلانات على مستوى المجموعة ذات الاهتمامات المشتركة إلى أقصى حد والتي تستوفي حدود "التصنيف الأساسي" (k-anon)؟

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

من المنظور التكتيكي، يمكنك التفكير في ما يلي:

  • لبدء عرض إعلان جديد، ما عليك سوى بدء تقديم عروض أسعار له في الحالات التي تريد عرضه فيها. وبالتالي، ليس عليك اتّخاذ أي إجراء إضافي.
  • يمكنك إنشاء إعلان احتياطي تستخدمه عندما لا تكون الإعلانات الجديدة k-anon. هناك بعض المخاطر بأن يكون الإعلان الاحتياطي نفسه k-anon، لذا يمكنك في بعض الأحيان الاكتفاء بتقديم عروض أسعار للإعلان الاحتياطي في المقام الأول. يمكنك إجراء ذلك بنسبة 1% من الوقت، على سبيل المثال، إذا كان هذا مستوى جيدًا لضمان توقع أن يظل الاحتياطي الاحتياطي فوق الحد.

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

كل مراجع Protected Audience API

تتوفر الأدلة المرجعية لواجهة برمجة التطبيقات:

يوفّر الشرح في Protected Audience API أيضًا تفاصيل حول إتاحة الميزات والقيود المفروضة عليها.