داده های مخاطب را تعریف کنید

یاد بگیرید که چگونه با ایجاد یک گروه علاقه‌مندی با استفاده از API مخاطبان محافظت‌شده، مخاطب را تعریف کنید. برای چرخه کامل عمر API مخاطبان محافظت‌شده، راهنمای توسعه‌دهنده را بخوانید و برای توضیح کامل نحوه ثبت گروه‌های علاقه‌مندی توسط مرورگرها ، به توضیح API مخاطبان محافظت‌شده مراجعه کنید.

توسعه‌دهنده نیستید؟ به مرور کلی API مخاطبان محافظت‌شده مراجعه کنید.

گروه‌های ذینفع API مخاطبان محافظت‌شده

یک گروه ذینفع API مخاطبان محافظت‌شده، گروهی از افراد با علایق مشترک را نشان می‌دهد که مطابق با یک لیست بازاریابی مجدد است. هر گروه ذینفع API مخاطبان محافظت‌شده یک مالک دارد.

صاحبان گروه‌های ذی‌نفع در مزایده تبلیغات Protected Audience API به عنوان خریدار عمل می‌کنند. عضویت در گروه‌های ذی‌نفع توسط مرورگر، در دستگاه کاربر ذخیره می‌شود و با فروشنده مرورگر یا هیچ کس دیگری به اشتراک گذاشته نمی‌شود.

توابع 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 که به تابع ارسال می‌شود نباید بیش از ۵۰ کیلوبایت حجم داشته باشد، در غیر این صورت فراخوانی با شکست مواجه می‌شود. پارامتر دوم مدت زمان گروه علاقه‌مندی را مشخص می‌کند که حداکثر ۳۰ روز است. فراخوانی‌های متوالی، مقادیر ذخیره شده قبلی را بازنویسی می‌کنند.

خواص مورد نیاز

تنها ویژگی‌های مورد نیاز برای گروه‌های ذینفع، owner و name هستند:

خواص اختیاری

ویژگی‌های باقی‌مانده اختیاری هستند:

biddingLogicUrl ^{1 ، 2}

مثال: https://dsp.example/bid/custom-bikes/bid.js

نقش: آدرس اینترنتی برای پیشنهاد اجرای جاوا اسکریپت در برگه کار.

biddingWasmHelperUrl ^{1 ، 2}

مثال: https://dsp.example/bid/custom-bikes/bid.wasm

نقش: آدرس اینترنتی (URL) برای کد WebAssembly که از biddingLogicUrl گرفته شده است.

updateUrl ^۲

مثال: https://dsp.example/bid/custom-bikes/update

نقش: آدرس اینترنتی که JSON را برای به‌روزرسانی ویژگی‌های گروه‌های علاقه‌مند برمی‌گرداند. ( به به‌روزرسانی داده‌های مخاطب و به‌روزرسانی تبلیغات مراجعه کنید.)

trustedBiddingSignalsUrl ²

مثال: https://dsp.example/trusted/bidding-signals

نقش: آدرس اینترنتی پایه برای درخواست‌های کلید-مقدار به سرویس کلید/مقدار مورد اعتماد پیشنهاددهنده.

trustedBiddingSignalsKeys

مثال: ['key1', 'key2' ...]

نقش: کلیدهایی برای درخواست‌ها به سرویس کلید/مقدار قابل اعتماد با کلید-مقدار.

userBiddingSignals

مثال: {...}

نقش: فراداده‌های اضافی که مالک می‌تواند در طول پیشنهاد قیمت از آنها استفاده کند.

ads ^۱

مثال: [bikeAd1, bikeAd2, bikeAd3]

نقش: تبلیغاتی که ممکن است برای این گروه ذینفع نمایش داده شود.

adComponents

مثال: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]

نقش: اجزایی برای تبلیغات متشکل از چندین قطعه .

^۱- ویژگی‌های biddingLogicUrl و ads اختیاری هستند، اما برای شرکت در یک حراجی الزامی هستند. ممکن است موارد استفاده‌ای برای ایجاد یک گروه علاقه‌مندی بدون این ویژگی‌ها وجود داشته باشد: برای مثال، ممکن است صاحب یک گروه علاقه‌مندی بخواهد یک مرورگر را برای کمپینی که هنوز اجرا نشده است یا برای استفاده دیگری در آینده به گروه علاقه‌مندی اضافه کند، یا ممکن است موقتاً بودجه تبلیغات آنها تمام شده باشد.

^۲ در پیاده‌سازی فعلی API مخاطب محافظت‌شده، biddingLogicUrl ، biddingWasmHelperUrl ، updateUrl و trustedBiddingSignalsUrl باید دارای منشأ یکسانی با owner باشند. این ممکن است یک محدودیت بلندمدت نباشد و 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() را فراخوانی کند تا از مرورگر بخواهد گروه علاقه‌مندی را حذف کند.

کد یک تبلیغ همچنین می‌تواند این تابع را برای گروه مورد نظر خود فراخوانی کند.

سوالات متداول

حداکثر تعداد گروه‌های ذینفع به ازای هر مالک گروه برای یک کاربر واحد چقدر است؟

کروم به ازای هر مالک تا ۱۰۰۰ گروه علاقه‌مندی و تا ۱۰۰۰ مالک گروه علاقه‌مندی را مجاز می‌داند. این محدودیت‌ها به عنوان محافظ در نظر گرفته شده‌اند و نباید در عملکرد عادی به آنها برخورد کرد.

چگونه می‌توانم تبلیغات گروه‌های ذی‌نفع را که آستانه‌های ناشناس بودن را برآورده می‌کنند، به حداکثر برسانم؟

همانطور که توضیح‌دهنده عمومی اشاره می‌کند، از آنجایی که یک گروه ذینفع می‌تواند چندین تبلیغ ممکن را که ممکن است نمایش دهد، ارائه دهد، این گروه فرصتی خواهد داشت تا هر زمان که انتخاب ترجیحی‌اش کمتر از آستانه باشد، یکی دیگر از تبلیغات خود را به عنوان "تبلیغ جایگزین" دوباره پیشنهاد دهد. این بدان معناست که یک تبلیغ کوچک و تخصصی که هنوز کمتر از آستانه ناشناس بودن 𝑘 است، همچنان می‌تواند در مزایده‌ها شرکت کند و گروه ذینفع آن راهی برای بازگشت به یک تبلیغ عمومی‌تر دارد تا زمانی که تبلیغ تخصصی‌تر مخاطبان کافی داشته باشد.

از دیدگاه تاکتیکی، می‌توانید موارد زیر را در نظر بگیرید:

• برای شروع نمایش یک تبلیغ جدید، کافیست در مواردی که می‌خواهید نمایش داده شود، پیشنهاد قیمت بدهید. هیچ کار اضافی لازم نیست انجام دهید.
• می‌توانید یک تبلیغ جایگزین داشته باشید که وقتی تبلیغات جدید ناشناس نیستند از آن استفاده کنید. این خطر وجود دارد که خود تبلیغ جایگزین شما ناشناس نباشد، بنابراین می‌توانید گاهی اوقات از همان ابتدا فقط با تبلیغ جایگزین پیشنهاد قیمت دهید. مثلاً شاید این کار را ۱٪ مواقع انجام دهید، اگر این سطح خوبی است تا مطمئن شوید که انتظار دارید تبلیغ جایگزین بالاتر از آستانه باقی بماند.

اخیراً بحث‌هایی در مورد روش‌های دیگر کارکرد این API صورت گرفته است، بنابراین اگر موردی برای استفاده دارید که این مکانیسم در آن مشکل ایجاد می‌کند، به مشارکت در گفتگوی عمومی در مورد راه‌های بهبود آن ادامه دهید.

تمام مراجع API مخاطبان محافظت‌شده

راهنماهای مرجع API در دسترس هستند:

• راهنمای برنامه‌نویس برای API مخاطبان محافظت‌شده .
• راهنمای خرید آگهی برای گروه‌های ذینفع مخاطب محافظت‌شده و تولید پیشنهاد .
• راهنمای فروشنده آگهی برای مزایده تبلیغات مخاطب محافظت شده.
• راهنمای گزارش نتایج مزایده
• بهترین روش‌ها برای تأخیر حراج تبلیغات مخاطب محافظت‌شده
• عیب یابی مخاطب محافظت شده

توضیح دهنده Protected Audience API همچنین جزئیاتی در مورد پشتیبانی از ویژگی ها و محدودیت ها ارائه می دهد.