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

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

يتطلّب تطبيق "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:

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

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

السمات المتبقية اختيارية:

biddingLogicUrl1، 2
مثال: https://dsp.example/bid/custom-bikes/bid.js
الدور: عنوان URL لإعداد عروض الأسعار التي يتم تشغيل JavaScript فيها في الوظيفة المصغّرة.
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 بما يصل إلى 1000 مجموعة اهتمام لكل مالك، وما يصل إلى 1000 مالك مجموعة اهتمامات. تهدف هذه الحدود إلى كونها حواجز حماية، ولا يتم اختراقها أثناء العمليات العادية.

كيف يمكنني زيادة الإعلانات المستندة إلى مجموعة الاهتمامات إلى أقصى حد بما يتوافق مع حدود شبكة الإعلانات ألفا؟

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

من ناحية التكتيكية، يمكنك أخذ النقاط التالية في الاعتبار:

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

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

كل مراجع Protected Audience API

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

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