این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

راهنمای توسعه دهنده FLEDGE API

این مقاله برای چه کسانی است؟

این پست یک مرجع فنی به تکرار فعلی API آزمایشی مخاطبان محافظت شده است.

Protected Audience API یک نمای کلی کمتر فنی از پیشنهاد است و همچنین دارای یک واژه نامه است.
نسخه نمایشی Protected Audience شرحی از استقرار اولیه FLEDGE را ارائه می دهد.
ویدیوی نمایشی «مخاطب محافظت‌شده» نحوه عملکرد کد نمایشی را توضیح می‌دهد و نحوه استفاده از ابزارهای توسعه‌دهنده Chrome برای اشکال‌زدایی مخاطبان محافظت‌شده را نشان می‌دهد.

مخاطب محافظت شده چیست؟

Protected Audience API یک پیشنهاد Privacy Sandbox برای ارائه بازاریابی مجدد و موارد استفاده از مخاطبان سفارشی است که به گونه‌ای طراحی شده است که توسط اشخاص ثالث برای ردیابی رفتار مرور کاربران در سایت‌ها قابل استفاده نباشد. API مزایده های روی دستگاه توسط مرورگر را قادر می سازد تا تبلیغات مرتبط را برای وب سایت هایی که کاربر قبلاً بازدید کرده است انتخاب کند.

مخاطب محافظت شده اولین آزمایشی است که در Chromium در خانواده پیشنهادات TURTLEDOVE اجرا شده است.

نمودار زیر نمای کلی از چرخه عمر FLEDGE را ارائه می دهد:

تصویری که نمای کلی هر مرحله از چرخه حیات FLEDGE را ارائه می دهد — چرخه عمر FLEDGE

چگونه می توانم مخاطب محافظت شده را امتحان کنم؟

نسخه ی نمایشی مخاطبان محافظت شده

خلاصه ای از استقرار مخاطبین محافظت شده اولیه در سایت های تبلیغ کننده و ناشر در protected-audience-demo.web.app در دسترس است.

ویدئوی نمایشی نحوه کارکرد کد نمایشی را توضیح می‌دهد و نحوه استفاده از ابزارهای توسعه‌دهنده کروم را برای اشکال‌زدایی مخاطب محافظت شده نشان می‌دهد.

در آزمایشی مبدأ مخاطب محافظت شده شرکت کنید

یک نسخه آزمایشی مبدا مربوط به جعبه ایمنی حریم خصوصی و اندازه‌گیری در Chrome Beta 101.0.4951.26 و بالاتر روی دسک‌تاپ برای مخاطبین محافظت‌شده، موضوعات و APIهای گزارش انتساب در دسترس قرار گرفته است.

برای شرکت، برای یک نشانه آزمایشی مبدا ثبت نام کنید .

هنگامی که با موفقیت در دوره آزمایشی ثبت نام کردید، می توانید API جاوا اسکریپت مخاطبین محافظت شده را در صفحاتی که یک نشانه آزمایشی معتبر ارائه می دهند امتحان کنید: به عنوان مثال، از مرورگر بخواهید به یک یا چند گروه علاقه مند بپیوندد و سپس یک حراج تبلیغاتی را اجرا کنید . یک تبلیغ را انتخاب و نمایش دهید.

نسخه ی نمایشی «مخاطب محافظت شده» یک مثال اساسی از استقرار مخاطب محافظت شده سرتاسر ارائه می دهد.

برای هر صفحه ای که می خواهید کد API مخاطب محافظت شده را اجرا کنید، یک نشانه آزمایشی ارائه دهید:

به عنوان یک متا تگ در <head>:
<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
به عنوان هدر HTTP:
Origin-Trial: TOKEN_GOES_HERE

با ارائه یک توکن به صورت برنامه ای:

const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

یک iframe که کد مخاطب محافظت‌شده را اجرا می‌کند - مانند فراخوانی navigator.joinAdInterestGroup() توسط مالک گروه علاقه‌مند - باید رمزی ارائه کند که با مبدا آن مطابقت داشته باشد.

Proposed First Protected Audience Origin Trial Details جزئیات بیشتری درباره اهداف آزمایش اول ارائه می دهد و توضیح می دهد که چه ویژگی هایی پشتیبانی می شوند.

این API را تست کنید

می‌توانید مخاطب محافظت‌شده را برای یک کاربر در Chrome Beta 101.0.4951.26 و بالاتر روی دسک‌تاپ آزمایش کنید:

با فعال کردن همه APIهای حریم خصوصی آگهی در chrome://settings/adPrivacy
با تنظیم پرچم از خط فرمان.

تبلیغات را در iframe یا قاب های حصاردار ارائه دهید

بسته به اینکه کدام پرچم‌ها تنظیم شده‌اند، تبلیغات می‌توانند در <iframe> یا <fencedframe> ارائه شوند.

برای استفاده از <fencedframe> برای ارائه تبلیغات:

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

برای استفاده از <iframe> برای ارائه تبلیغات:

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

پرچم BiddingAndScoringDebugReportingAPI را برای فعال کردن روش‌های گزارش موقت اشکال زدایی از دست دادن/برنده اضافه کنید.

اجرای Chromium with flags نحوه تنظیم پرچم هنگام اجرای Chrome و سایر مرورگرهای مبتنی بر Chromium را از خط فرمان توضیح می دهد. فهرست کامل پرچم‌های مخاطب محافظت شده از جستجوی کد Chromium در دسترس است.

توجه: این یک نسخه در حال پیشرفت از مخاطبان محافظت شده برای آزمایش اولیه است. نباید کامل یا نشان دهنده اجرای نهایی در نظر گرفته شود. پیشرفت و وضعیت حضار محافظت شده در جلسات منظم WICG مورد بحث قرار می گیرد. در صورتجلسه فراخوان WICG 2021-05-12 جزئیاتی درباره مواردی که در اجرای فعلی پشتیبانی می‌شوند و چه مواردی پشتیبانی نمی‌شوند، ارائه می‌کند. جدول زمانی Privacy Sandbox اطلاعات زمان‌بندی پیاده‌سازی را برای مخاطبین محافظت‌شده و سایر پیشنهادات جعبه ایمنی حریم خصوصی ارائه می‌دهد.

چه ویژگی هایی در آخرین نسخه کروم پشتیبانی می شود؟

مخاطب محافظت‌شده به‌عنوان اولین آزمایش برای آزمایش ویژگی‌های پیشنهادی مخاطب محافظت‌شده ، پشت پرچم‌های ویژگی در Chromium در دسترس قرار می‌گیرد:

گروه‌های علاقه : توسط مرورگر ذخیره می‌شود، همراه با ابرداده‌های مرتبط برای پیکربندی مناقصه و رندر آگهی.
مناقصه روی دستگاه توسط خریداران (DSP یا تبلیغ‌کننده) : براساس گروه‌های ذینفع ذخیره‌شده و سیگنال‌های فروشنده.
انتخاب آگهی روی دستگاه توسط فروشنده (SSP یا ناشر) : بر اساس پیشنهادات حراج و ابرداده از خریداران.
رندر آگهی در یک نسخه به طور موقت آرام از فریم های حصاردار : با دسترسی به شبکه و ثبت گزارش برای رندر آگهی مجاز است.

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

مجوزهای گروه علاقه

پیش‌فرض در اجرای فعلی Protected Audience این است که اجازه فراخوانی joinAdInterestGroup() از هر نقطه‌ای در صفحه، حتی از iframe‌های متقابل دامنه می‌دهد. در آینده، هنگامی که صاحبان سایت وقت داشته باشند تا خط‌مشی‌های مجوزهای iframe متقابل دامنه خود را تنظیم کنند، برنامه این است که تماس از میان دامنه‌های iframe را ممنوع کنند، همانطور که توضیح دهنده توضیح می‌دهد.

خدمات کلید/ارزش

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

کد سرویس کلید/مقدار مخاطب محافظت شده اکنون در مخزن GitHub Sandbox Privacy در دسترس است. این سرویس برای توسعه دهندگان کروم و اندروید قابل استفاده است. برای به روز رسانی وضعیت ، پست وبلاگ اعلامیه را بررسی کنید. از توضیح‌دهنده API و توضیح‌دهنده مدل اعتماد ، درباره سرویس کلید/مقدار مخاطب محافظت‌شده بیشتر بیاموزید.

برای تست اولیه از مدل "Bring Your Own Server" استفاده شده است. در درازمدت، Adtech ها باید از سرویس های منبع باز کلید/ارزش مخاطب محافظت شده که در محیط های اجرایی قابل اعتماد برای بازیابی داده های بلادرنگ اجرا می شوند، استفاده کنند.

برای اطمینان از اینکه اکوسیستم زمان کافی برای آزمایش دارد، انتظار نداریم تا زمانی پس از منسوخ شدن کوکی های شخص ثالث، به استفاده از سرویس های کلید/ارزش منبع باز یا TEE نیاز داشته باشیم. ما اخطار قابل توجهی را برای توسعه دهندگان ارائه خواهیم داد تا قبل از انجام این انتقال، آزمایش و پذیرش را آغاز کنند.

شناسایی پشتیبانی از ویژگی ها

قبل از استفاده از 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');

چگونه می توانم از مخاطبین محافظت شده انصراف دهم؟

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

چگونه سایت ها می توانند دسترسی را کنترل کنند؟

مخاطب محافظت شده در نهایت از سایت‌ها می‌خواهد که یک خط‌مشی مجوز تنظیم کنند تا عملکرد مخاطب محافظت شده در دسترس باشد. این کمک می کند تا اطمینان حاصل شود که اشخاص ثالث دلخواه نمی توانند از API بدون اطلاع سایت استفاده کنند. با این حال، برای تسهیل آزمایش در طول اولین آزمایش اولیه ، این الزام به طور پیش‌فرض لغو می‌شود. سایت‌هایی که می‌خواهند صراحتاً عملکرد مخاطب محافظت‌شده را در طول دوره آزمایش غیرفعال کنند، می‌توانند از خط‌مشی مجوزهای مربوطه برای مسدود کردن دسترسی استفاده کنند.

دو خط مشی مجوز مخاطب محافظت شده وجود دارد که می توانند به طور مستقل تنظیم شوند:

join-ad-interest-group عملکرد را برای افزودن یک مرورگر به گروه های علاقه فعال/غیرفعال می کند
run-ad-auction عملکرد را برای اجرای حراج روی دستگاه فعال/غیرفعال می کند

دسترسی به APIهای مخاطب محافظت شده را می توان در زمینه های شخص اول با مشخص کردن خط مشی مجوزهای زیر در سرصفحه پاسخ HTTP غیرفعال کرد:

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

می‌توانید با افزودن ویژگی allow زیر به عنصر iframe، استفاده از APIها را در یک iframe غیرفعال کنید:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

بخش «اجازه‌های آزمایشی اولیه مخاطب محافظت‌شده پیشنهادی - سیاست» جزئیات بیشتری را ارائه می‌کند.

انصراف کاربر

کاربر می تواند با استفاده از هر یک از مکانیسم های زیر دسترسی به API مخاطب محافظت شده و سایر ویژگی های Privacy Sandbox را مسدود کند:

آزمایش‌های جعبه ایمنی حریم خصوصی را در تنظیمات Chrome غیرفعال کنید : تنظیمات > امنیت و حریم خصوصی > جعبه ایمنی حریم خصوصی . این نیز در chrome://settings/adPrivacy قابل دسترسی است.
غیرفعال کردن کوکی‌های شخص ثالث در تنظیمات Chrome: تنظیمات > امنیت و حریم خصوصی .
کوکی‌ها و سایر داده‌های سایت را روی «مسدود کوکی‌های شخص ثالث» یا «مسدود کردن همه کوکی‌ها» از chrome://settings/cookies تنظیم کنید.
از حالت ناشناس استفاده کنید.

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

اشکال زدایی ورکلت های مخاطب محافظت شده

از Chrome Canary 98.0.4718.0، می‌توانید Worklets Protected Audience را در Chrome DevTools اشکال‌زدایی کنید.

اولین گام این است که نقاط شکست را از طریق یک دسته جدید در پنجره Event Liner Breakpoints در پانل Sources تنظیم کنید.

تصویری از DevTools در Chrome Canary، با برجسته کردن قسمت Event Liner Breakpoints در پانل Sources. شروع مرحله مناقصه مناقصه در زیر کارنامه مزایده آگهی انتخاب شده است.

هنگامی که یک نقطه شکست فعال می شود، اجرا قبل از اولین عبارت در سطح بالای اسکریپت Worklet متوقف می شود. می‌توانید از نقاط شکست معمولی یا دستورات مرحله‌ای برای رسیدن به خود تابع مناقصه/ امتیازدهی/گزارش استفاده کنید.

اسکریپت های Worklet زنده نیز در زیر پنل Threads نمایش داده می شوند.

اسکرین شات DevTools در Chrome Canary، با برجسته کردن قسمت Threads در پانل Sources، اسکریپت Worklet فعلی را نشان می‌دهد که موقتاً متوقف شده است.

از آنجایی که برخی از Worklet ها ممکن است به صورت موازی اجرا شوند، ممکن است چندین رشته در آنجا در حالت "مکث" قرار گیرند. می‌توانید از لیست رشته‌ها برای جابه‌جایی بین رشته‌ها استفاده کنید و در صورت لزوم، آنها را از سر بگیرید یا دقیق‌تر بررسی کنید.

رویدادهای مخاطب محافظت شده را مشاهده کنید

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

اگر از سایت خرید نمایشی مخاطب محافظت شده در مرورگری که مخاطب محافظت شده فعال است بازدید کنید، DevTools اطلاعات مربوط به رویداد join را نمایش می دهد.

پانل برنامه DevTools در Chrome Canary، اطلاعاتی را درباره رویداد پیوستن به گروه مورد علاقه مخاطب محافظت شده نشان می‌دهد.

اکنون، اگر در مرورگری که مخاطب محافظت شده فعال است، از سایت ناشر نمایشی مخاطب محافظت شده بازدید کنید، DevTools اطلاعات مربوط به bid و رویدادهای win نمایش می دهد.

پانل برنامه DevTools در Chrome Canary، اطلاعاتی را در مورد پیشنهاد حراج مخاطب محافظت شده و رویدادهای برنده نشان می دهد.

API مخاطب محافظت شده چگونه کار می کند؟

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

هشدار: همه ویژگی‌های شرح‌داده‌شده در این پست در نسخه‌ای از API مخاطب محافظت‌شده که در حال حاضر در Chrome آزمایش می‌شود، پیاده‌سازی نشده‌اند (یا به‌طور کامل پیاده‌سازی نشده‌اند). تست با پرچم‌های ویژگی توضیح می‌دهد که در حال حاضر چه ویژگی‌های مخاطب محافظت شده برای آزمایش در Chrome اجرا شده از خط فرمان با استفاده از پرچم‌های ویژگی در دسترس هستند. ما انتظار داریم با ادامه کار بر روی پیاده سازی، ویژگی های مخاطب محافظت شده به مرور زمان اضافه شود. هنگامی که API به مرحله آزمایشی اصلی رسید، فهرستی به‌روزرسانی منظم از قسمت‌هایی که قبلاً پیاده‌سازی شده‌اند و آنچه هنوز در حال انجام است ارائه می‌کنیم.

1. کاربر از سایت تبلیغ کننده بازدید می کند

تصویری که فردی را در حال بازدید از سایت سازنده دوچرخه سفارشی در مرورگر لپ‌تاپ خود نشان می‌دهد.

تصور کنید که کاربری از وب سایت یک دوچرخه ساز سفارشی ( تبلیغ کننده در این مثال) بازدید می کند و مدتی را در صفحه محصول برای یک دوچرخه فولادی دست ساز می گذراند. این یک فرصت بازاریابی مجدد را برای سازنده دوچرخه فراهم می کند.

اصطلاح کلیدی: پلتفرم سمت تقاضا (DSP) یک سرویس Adtech است که برای خودکارسازی خرید تبلیغات استفاده می شود. DSP ها توسط تبلیغ کنندگان برای خرید نمایش تبلیغات در طیف وسیعی از سایت های ناشر استفاده می شود. ناشران موجودی تبلیغات خود را از طریق بازارهایی به نام صرافی های تبلیغاتی برای فروش قرار می دهند و DSP ها به صورت برنامه ریزی شده تصمیم می گیرند که کدام یک از تبلیغات موجود برای تبلیغ کننده برای خرید منطقی تر است. پلتفرم سمت عرضه (SSP) یک سرویس adtech است که برای خودکارسازی موجودی فروش آگهی استفاده می شود. SSP ها به ناشران اجازه می دهند موجودی خود را (مستطیل های خالی که تبلیغات در آن قرار می گیرند) به چند صرافی تبلیغاتی، DSP و شبکه ارائه دهند. این امر طیف وسیعی از خریداران بالقوه را قادر می سازد تا برای فضای تبلیغاتی پیشنهاد دهند.

2. از مرورگر کاربر خواسته می شود که یک گروه علاقه مندی را اضافه کند

تصویری که شخصی را در حال مشاهده یک سایت در مرورگر روی لپ تاپ خود نشان می دهد. کد جاوا اسکریپت joinAdInterestGroup() در مرورگر در حال اجرا است.

بخش توضیح دهنده: مرورگرها گروه های علاقه را ثبت می کنند

پلتفرم سمت تقاضای تبلیغ‌کننده (DSP) (یا خود تبلیغ‌کننده) navigator.joinAdInterestGroup() را فرا می‌خواند تا از مرورگر بخواهد یک گروه علاقه‌مند را به لیست گروه‌هایی که مرورگر در آن عضو است اضافه کند. در این مثال، گروه custom-bikes نام دارد و مالک آن dsp.example است. مالک گروه ذینفع (در این مورد، DSP) یک خریدار در مزایده آگهی شرح داده شده در مرحله 4 خواهد بود. عضویت در گروه علاقه‌مندی توسط مرورگر، در دستگاه کاربر ذخیره می‌شود و با فروشنده مرورگر یا شخص دیگری به اشتراک گذاشته نمی‌شود.

توجه: مبدا متن فراخوانی joinAdInterestGroup() باید با مبدا مالک گروه علاقه مطابقت داشته باشد، بنابراین joinAdInterestGroup() باید از یک iframe فراخوانی شود (مثلاً از یک DSP) مگر اینکه مبدا مالک گروه علاقه منطبق باشد مبدأ سند فعلی (به عنوان مثال، یک وب سایت با گروه های ذینفع خود). runAdAuction الزامات یکسانی ندارد، بنابراین فراخوانی runAdAuction() از یک تگ <script> احتمالاً بسیار کارآمدتر از iframe متقاطع است.

joinAdInterestGroup() به مجوز نیاز دارد:

سایت در حال بازدید
مالک گروه ذینفع

برای مثال: نباید برای malicious.example امکان فراخوانی joinAdInterestGroup() با dsp.example به عنوان مالک بدون اجازه dsp.example وجود داشته باشد.

مجوز از سایت در حال بازدید

همان مبدا : به طور پیش‌فرض، مجوز به طور ضمنی برای joinAdInterestGroup() از همان مبدأ سایت مورد بازدید، یعنی از همان مبدأ فریم سطح بالای صفحه فعلی، اعطا می‌شود. سایت‌ها می‌توانند از هدر خط‌مشی مجوزهای join-ad-interest-group محافظت‌شده برای غیرفعال کردن فراخوان‌های joinAdInterestGroup() استفاده کنند.

مبدا متقاطع : فراخوانی joinAdInterestGroup() از مبداهایی که با صفحه فعلی متفاوت هستند، تنها در صورتی می تواند موفق باشد که سایت مورد بازدید یک خط مشی مجوز تنظیم کرده باشد که به تماس ها برای joinAdInterestGroup() از iframe های متقاطع می تواند موفق شود.

توجه: پیش‌فرض در اجرای فعلی Protected Audience این است که به تماس‌ها اجازه می‌دهد از هر نقطه در صفحه، حتی از iframe‌های متقاطع joinAdInterestGroup() . در آینده، هنگامی که صاحبان سایت زمان لازم را برای تنظیم خط‌مشی‌های مجوزهای خود داشته باشند، این طرح به‌طور پیش‌فرض اجازه نمی‌دهد که تماس‌های iframes با منبع متقاطع، همانطور که در توضیح مخاطب محافظت‌شده توضیح داده شده است، نباشد.

اجازه از صاحب گروه ذینفع

مجوز مالک گروه علاقه به طور ضمنی با فراخوانی joinAdInterestGroup() از یک iframe با همان مبدا مالک گروه علاقه‌مند داده می‌شود. برای مثال، یک iframe dsp.example می‌تواند joinAdInterestGroup() برای گروه‌های ذینفع متعلق به dsp.example فراخوانی کند.

پیشنهاد این است که joinAdInterestGroup() می تواند در یک صفحه یا iframe در دامنه مالک اجرا شود، یا به دامنه های دیگر ارائه شده با استفاده از یک لیست در یک URL .well-known . واگذار شود.

با استفاده از navigator.joinAdInterestGroup()

در اینجا مثالی از نحوه استفاده از API آورده شده است:

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

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

شیء interestGroup ارسال شده به تابع نباید بیش از 50 کیلوبایت اندازه داشته باشد، در غیر این صورت فراخوانی ناموفق خواهد بود. پارامتر دوم مدت زمان گروه ذینفع را مشخص می کند که حداکثر 30 روز است. تماس های پی در پی مقادیر ذخیره شده قبلی را بازنویسی می کنند.

نکته کلیدی: همه نشانی‌های اینترنتی که به عنوان پارامتر برای روش‌های API مخاطب محافظت شده استفاده می‌شوند باید از منابع امن باشند: همه منابع باید از طریق URL‌های HTTPS ارائه شوند. نحوه استفاده از HTTPS برای توسعه محلی نحوه انجام این کار را هنگام اجرای Protected Audience به صورت محلی توضیح می دهد. علاوه بر این، biddingLogicUrl ، decisionLogicUrl ، و trustedBiddingSignals همگی به یک هدر پاسخ HTTP X-Allow-FLEDGE: true نیاز دارند.

خواص گروه بهره

اموال	مورد نیاز	مثال	نقش
`owner`	مورد نیاز	`'https://dsp.example'`	منشاء مالک گروه ذینفع.
`name`	مورد نیاز	`'custom-bikes'`	نام گروه ذینفع
`biddingLogicUrl` **	اختیاری*	`'https://dsp.example/bid/custom-bikes/bid.js'`	URL برای پیشنهاد جاوا اسکریپت اجرا شده در Worklet.
`biddingWasmHelperUrl` **	اختیاری*	`'https://dsp.example/bid/custom-bikes/bid.wasm'`	URL برای کد WebAssembly که از `biddingLogicUrl` هدایت می شود.
`dailyUpdateUrl` **	اختیاری	`'https://dsp.example/bid/custom-bikes/update'`	URL که JSON را برای به‌روزرسانی ویژگی‌های گروه علاقه برمی‌گرداند. ( به به روز رسانی گروه علاقه مند مراجعه کنید.)
`trustedBiddingSignalsUrl` **	اختیاری	`'https://dsp.example/trusted/bidding-signals'`	URL پایه برای درخواست های کلید-مقدار به سرور مورد اعتماد پیشنهاد دهنده.
`trustedBiddingSignalsKeys`	اختیاری	`['key1', 'key2' ...]`	کلیدهای درخواست به سرور مورد اعتماد با ارزش کلید.
`userBiddingSignals`	اختیاری	`{...}`	فراداده اضافی که مالک می تواند در حین مناقصه استفاده کند.
`ads`	اختیاری*	`[bikeAd1, bikeAd2, bikeAd3]`	تبلیغاتی که ممکن است برای این گروه علاقه ارائه شود.
`adComponents`	اختیاری	`[customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]`	اجزای تبلیغات متشکل از چندین قطعه .

* تمام خواص به جز owner و name اختیاری هستند. ویژگی‌های biddingLogicUrl و ads اختیاری هستند، اما برای شرکت در مزایده لازم است. ممکن است موارد استفاده ای برای ایجاد یک گروه علاقه بدون این ویژگی ها وجود داشته باشد: برای مثال، یک مالک گروه علاقه ممکن است بخواهد مرورگری را به یک گروه علاقه مند برای کمپینی که هنوز اجرا نمی شود، یا برای استفاده های دیگر در آینده اضافه کند، یا آنها ممکن است به طور موقت بودجه تبلیغات تمام شده باشد.

** نشانی‌های اینترنتی biddingLogicUrl ، biddingWasmHelperUrl ، dailyUpdateUrl و trustedBiddingSignalsUrl باید منشا یکسانی با مالک داشته باشند. URL های ads و adComponents چنین محدودیتی ندارند.

ویژگی های گروه علاقه را به روز کنید

dailyUpdateUrl وب سروری را مشخص می‌کند که ویژگی‌های گروه علاقه تعریف JSON را برمی‌گرداند که مطابق با شی گروه علاقه ارسال شده به navigator.joinAdInterestGroup() . این مکانیسمی را برای مالک گروه فراهم می کند تا به طور دوره ای ویژگی های گروه ذینفع را به روز کند. در پیاده سازی فعلی ، ویژگی های زیر را می توان تغییر داد:

biddingLogicUrl
biddingWasmHelperUrl
trustedBiddingSignalsUrl
trustedBiddingSignalsKeys
ads
priority

هر فیلدی که در JSON مشخص نشده باشد بازنویسی نخواهد شد—فقط فیلدهای مشخص شده در JSON به روز می شوند—در حالی که فراخوانی navigator.joinAdInterestGroup() هر گروه مورد علاقه موجود را رونویسی می کند.

به روز رسانی بهترین تلاش است و ممکن است در شرایط زیر شکست بخورد:

مهلت درخواست شبکه (در حال حاضر 30 ثانیه).
خرابی شبکه دیگر
تجزیه JSON شکست خورد.

اگر زمان زیادی برای به‌روزرسانی صرف شده باشد، به‌روزرسانی‌ها نیز می‌توانند لغو شوند، اگرچه این محدودیتی برای به‌روزرسانی‌های لغو شده (باقیمانده) اعمال نمی‌کند. به روز رسانی ها با نرخ محدود به حداکثر یک در روز است. به روز رسانی هایی که به دلیل خطاهای شبکه با شکست مواجه می شوند، پس از یک ساعت دوباره امتحان می شوند و به روز رسانی هایی که به دلیل قطع شدن اتصال از اینترنت با شکست مواجه می شوند، بلافاصله پس از اتصال مجدد دوباره امتحان می شوند.

به روز رسانی های دستی

به‌روزرسانی‌های گروه‌های علاقه متعلق به مبدأ قاب فعلی را می‌توان به‌صورت دستی از طریق navigator.updateAdInterestGroups() فعال کرد. محدود کردن نرخ از انجام به‌روزرسانی‌ها مکرر جلوگیری می‌کند: تماس‌های مکرر با navigator.updateAdInterestGroups() تا زمانی که دوره محدودیت نرخ (در حال حاضر یک روز) سپری نشود، کاری انجام نمی‌دهند. اگر navigator.joinAdInterestGroup() مجدداً برای owner و name گروه ذینفع فراخوانی شود، محدودیت نرخ بازنشانی می‌شود.

به روز رسانی خودکار

همه گروه‌های علاقه‌مندی که برای یک حراج بارگیری می‌شوند، به‌طور خودکار پس از اتمام حراج به‌روزرسانی می‌شوند، مشروط به محدودیت‌های نرخی مشابه به‌روزرسانی‌های دستی. برای هر مالکی که حداقل یک گروه ذینفع در مزایده شرکت می کند، به این صورت است که گویی navigator.updateAdInterestGroups() از یک iframe فراخوانی می شود که منشاء آن با مالک آن مطابقت دارد.

تبلیغات را برای یک گروه علاقه مند مشخص کنید

ads و اشیاء adComponents شامل یک URL برای یک آگهی خلاقانه و به صورت اختیاری، ابرداده دلخواه است که می تواند در زمان مناقصه استفاده شود. به عنوان مثال:

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

خریداران چگونه پیشنهاد می دهند؟

اسکریپت موجود در biddingLogicUrl که توسط مالک گروه علاقه‌مند ارائه می‌شود باید دارای تابع generateBid() باشد. هنگامی که یک فروشنده فضای تبلیغاتی navigator.runAdAuction() را فرا می‌خواند ، generatedBid() یک بار برای هر یک از گروه‌های علاقه‌ای که مرورگر در آن عضو است، فراخوانی می‌شود، در صورتی که مالک گروه علاقه‌مند برای ارائه پیشنهاد دعوت شود. به عبارت دیگر، generateBid() یک بار برای هر تبلیغ کاندید فراخوانی می شود. فروشنده یک خاصیت decisionLogicUrl را در پارامتر پیکربندی مزایده ارائه می دهد که به navigator.runAdAuction() ارسال شده است. کد موجود در این URL باید شامل یک تابع scoreAd() باشد که برای هر پیشنهاد دهنده در مزایده اجرا می شود تا به هر یک از پیشنهادهای بازگردانده شده توسط generateBid() امتیاز دهد.

توجه: ویژگی biddingWasmHelperUrl اختیاری است، اما به متقاضی اجازه می‌دهد تا زیرروال‌های محاسباتی گران‌تری را در WebAssembly به جای جاوا اسکریپت ارائه کند تا از تابع جاوا اسکریپت ارائه شده توسط biddingLogicUrl هدایت شوند. در صورت ارائه، باید به یک باینری WebAssembly اشاره کند که با یک application/wasm mimetype ارائه شده است. WebAssembly.Module مربوطه توسط مرورگر برای تابع generateBid() در دسترس قرار می گیرد.

اسکریپت موجود در biddingLogicUrl که توسط یک خریدار فضای تبلیغاتی ارائه می‌شود باید دارای تابع generateBid() باشد. این تابع یک بار برای هر تبلیغ کاندید فراخوانی می شود. runAdAuction() به صورت جداگانه هر تبلیغ را همراه با پیشنهاد قیمت و ابرداده مربوط به آن بررسی می کند، سپس یک امتیاز عددی مطلوبیت را به تبلیغ اختصاص می دهد.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

generateBid() آرگومان های زیر را می گیرد:

interestGroup
شیء توسط خریدار آگهی به joinAdInterestGroup() ارسال شد. (گروه علاقه مند ممکن است از طریق dailyUpdateUrl به روز شود.)
auctionSignals
یک ویژگی از آرگومان پیکربندی مزایده توسط فروشنده ad-space به navigator.runAdAuction() ارسال شد. این اطلاعات در مورد زمینه صفحه (مانند اندازه آگهی و شناسه ناشر)، نوع حراج (قیمت اول یا قیمت دوم) و سایر ابرداده ها ارائه می کند.
perBuyerSignals
مانند auctionSignals ، یک ویژگی آرگومان پیکربندی مزایده توسط فروشنده به navigator.runAdAuction() ارسال شد. این می‌تواند سیگنال‌های متنی را از سرور خریدار در مورد صفحه ارائه دهد، اگر فروشنده یک SSP باشد که یک تماس پیشنهادی بی‌درنگ با سرورهای خریدار انجام می‌دهد و پاسخ را ارسال می‌کند، یا اگر صفحه ناشر مستقیماً با سرور خریدار تماس بگیرد. اگر چنین است، خریدار ممکن است بخواهد یک امضای رمزنگاری از آن سیگنال‌ها را در داخل ()geneBid به عنوان محافظت در برابر دستکاری بررسی کند.
trustedBiddingSignals
شیئی که کلیدهای آن trustedBiddingSignalsKeys برای گروه علاقه مند هستند و مقادیر آن در درخواست trustedBiddingSignals برگردانده می شوند.
browserSignals
یک شی ساخته شده توسط مرورگر، که ممکن است شامل اطلاعاتی در مورد زمینه صفحه (مانند hostname صفحه فعلی، که فروشنده در غیر این صورت می تواند جعل کند) و داده هایی برای خود گروه علاقه مند (مانند سابقه زمانی که گروه قبلاً برنده شده است) باشد. حراج، اجازه می دهد تا محدودیت فرکانس در دستگاه).

شی browserSignals دارای ویژگی های زیر است:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

برای محاسبه مقدار bid ، کد موجود در generateBid() می تواند از ویژگی های پارامترهای تابع استفاده کند. به عنوان مثال:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

generateBid() یک شی با چهار ویژگی برمی گرداند:

ad
فراداده های خودسرانه درباره آگهی، مانند اطلاعاتی که فروشنده انتظار دارد درباره این پیشنهاد یا آگهی خلاقانه یاد بگیرد. فروشنده](/privacy-sandbox/resources/glossary#ssp) از این اطلاعات در آگهی تبلیغاتی حراج و تصمیم خود استفاده می کند. فروشنده از این اطلاعات در منطق حراج و تصمیم گیری خود استفاده می کند.
bid
پیشنهاد عددی که وارد مزایده می شود. فروشنده باید در موقعیتی باشد که بتواند پیشنهادات خریداران مختلف را با هم مقایسه کند، بنابراین پیشنهادها باید در یک واحد انتخاب شده توسط فروشنده باشد (مثلاً "دلار در هزار دلار"). اگر پیشنهاد صفر یا منفی باشد، این گروه ذینفع به هیچ وجه در مزایده فروشنده شرکت نمی کند. با استفاده از این مکانیسم، خریدار می‌تواند قوانین تبلیغ‌کننده را برای مکان‌هایی که ممکن است آگهی‌هایشان ظاهر شود یا نشوند، اجرا کند.
render
یک نشانی وب یا فهرستی از نشانی‌های وب، که در صورت برنده شدن این پیشنهاد در حراج، برای ارائه خلاقیت استفاده می‌شود. (به تبلیغات متشکل از چند قطعه در توضیح API مراجعه کنید.) مقدار باید با renderUrl یکی از تبلیغات تعریف شده برای گروه علاقه مطابقت داشته باشد.
adComponents
فهرستی اختیاری از حداکثر 20 مؤلفه برای تبلیغات متشکل از چندین قطعه ، که از ویژگی adComponents آرگومان گروه علاقه‌ای که به navigator.joinAdInterestGroup() منتقل شده است، گرفته شده است.

درخواست از یک مرورگر برای ترک یک گروه علاقه مند

مالک گروه علاقه مند می تواند درخواست کند که یک مرورگر از یک گروه علاقه حذف شود. به عبارت دیگر، از مرورگر خواسته می شود تا گروه مورد علاقه را از لیست افرادی که عضو آنهاست حذف کند.

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

اگر کاربر به سایتی برگردد که از مرورگر خواسته است یک گروه علاقه اضافه کند، مالک گروه علاقه‌مندی می‌تواند تابع navigator.leaveAdInterestGroup() فراخوانی کند تا از مرورگر درخواست کند گروه مورد علاقه را حذف کند. کد برای یک تبلیغ همچنین می تواند این تابع را برای گروه مورد علاقه خود فراخوانی کند.

3. کاربر از سایتی بازدید می کند که فضای تبلیغاتی را می فروشد

تصویری که فردی را در حال بازدید از یک وب سایت خبری در مرورگر لپ تاپ خود نشان می دهد. سایت دارای یک جایگاه تبلیغاتی خالی است.

بعداً کاربر از سایتی بازدید می کند که فضای تبلیغاتی را می فروشد، در این مثال یک وب سایت خبری. این سایت دارای موجودی آگهی است که به صورت برنامه ریزی شده با استفاده از مناقصه زمان واقعی به فروش می رساند.

توجه: سه نقش اصلی در توضیح پیشنهاد مخاطب محافظت شده شرح داده شده است: * تبلیغ کننده : سایتی که برای تبلیغ محصولات خود هزینه می پردازد. در مثال اینجا، یک دوچرخه ساز سفارشی. * ناشر : سایت هایی که فضای تبلیغاتی را می فروشند، مانند وب سایت خبری آنلاین که در مثال های اینجا ذکر شده است. بسیاری از (و نه همه) سایت های فروش فضای تبلیغاتی ناشر محتوا هستند. * فروشنده : طرفی که حراج آگهی را اجرا می کند (در مرحله بعدی). اکثر ناشران از یک سرویس adtech مانند SSP برای بهینه سازی موجودی آگهی فروش استفاده می کنند.

4. یک مزایده تبلیغاتی در مرورگر اجرا می شود

تصویری که شخصی را در حال مشاهده یک وب سایت خبری در مرورگر لپ تاپ خود نشان می دهد. یک مزایده تبلیغاتی با استفاده از Protected Audience API در حال انجام است.

بخش توضیح دهنده: فروشندگان مزایده های روی دستگاه را اجرا می کنند

حراج آگهی احتمالاً توسط SSP ناشر یا خود ناشر اجرا می شود. هدف از حراج انتخاب مناسب ترین آگهی برای یک جایگاه آگهی موجود در صفحه فعلی است. حراج گروه‌های علاقه‌ای را که مرورگر در آنها عضو است، به همراه داده‌های خریداران فضای آگهی و فروشندگان خدمات کلید/ارزش در نظر می‌گیرد.

فروشنده فضای تبلیغاتی با فراخوانی navigator.runAdAuction() از مرورگر کاربر درخواست می کند تا حراج تبلیغات را شروع کند.

به عنوان مثال:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

runAdAuction() قولی را برمی‌گرداند که به یک URN ( urn:uuid:<something> ) که نشان‌دهنده نتیجه حراج آگهی است، حل می‌شود. این فقط زمانی می تواند توسط مرورگر رمزگشایی شود که به یک قاب محصور برای رندر منتقل شود: صفحه ناشر نمی تواند آگهی برنده را بازرسی کند.

توجه: همانطور که قبلا توضیح داده شد، مبدا متن فراخوانی برای joinAdInterestGroup() باید با مبدأ مالک گروه علاقه مطابقت داشته باشد، بنابراین joinAdInterestGroup() باید از یک iframe (مثلاً از یک DSP) فراخوانی شود، مگر اینکه مبدا علاقه باشد. مالک گروه منشا سند فعلی را منطبق می کند (به عنوان مثال، یک وب سایت با گروه های ذینفع خودش). runAdAuction الزامات یکسانی ندارد، بنابراین فراخوانی runAdAuction() از یک تگ <script> احتمالاً بسیار کارآمدتر از iframe متقاطع است.

اسکریپت decisionLogicUrl هر آگهی را به همراه پیشنهاد و ابرداده مرتبط با آن، یک به یک در نظر می گیرد و سپس یک امتیاز عددی مطلوبیت به آن اختصاص می دهد.

خواص `auctionConfig`

اموال	مورد نیاز	مثال	نقش
`seller`	مورد نیاز	`'https://ssp.example'`	منشاء فروشنده.
`decisionLogicUrl`	مورد نیاز	`'https://ssp.example/auction-decision-logic.js'`	URL برای جاوا اسکریپت ورکلت حراج.
`trustedScoringSignalsUrl`	اختیاری	`'https://ssp.example/scoring-signals'`	URL سرور مورد اعتماد فروشنده.
`interestGroupBuyers*`	مورد نیاز	`['https://dsp.example', 'https://buyer2.example', ...]`	خاستگاه همه صاحبان گروه های ذینفع درخواست شده است که در حراج پیشنهاد دهند.
`auctionSignals`	اختیاری	`{...}`	اطلاعات فروشنده در مورد زمینه صفحه، نوع حراج و غیره.
`sellerSignals`	اختیاری	`{...}`	اطلاعات بر اساس تنظیمات ناشر، ایجاد یک درخواست آگهی متنی و غیره.
`sellerTimeout`	اختیاری	`100`	حداکثر زمان اجرا (ms) اسکریپت `scoreAd()` فروشنده.
`perBuyerSignals`	اختیاری	`{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ...}`	سیگنال های متنی در مورد صفحه برای هر خریدار خاص، از سرور آنها.
`perBuyerTimeouts`	اختیاری	`50`	حداکثر زمان اجرا (میلی‌ثانیه) اسکریپت‌های `generateBid()` خریدار خاص.
`componentAuctions`	اختیاری	`[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]`	تنظیمات اضافی برای حراج قطعات .

* فروشنده ممکن است interestGroupBuyers: '*' تا به همه گروه‌های ذینفع اجازه پیشنهاد دهد. سپس آگهی ها بر اساس معیارهایی غیر از درج مالک گروه مورد علاقه پذیرفته یا رد می شوند. به عنوان مثال، فروشنده ممکن است آگهی‌های خلاقانه را بررسی کند تا مطابقت با خط‌مشی‌های آن‌ها را تأیید کند.

** additionalBids در اجرای فعلی مخاطبین محافظت شده پشتیبانی نمی شود. برای اطلاعات بیشتر بخش شرکت کنندگان در حراج را در توضیح مخاطب محافظت شده بخوانید.

تبلیغات چگونه انتخاب می شوند؟

کد موجود در decisionLogicUrl (ویژگی از شی پیکربندی حراج که به runAdAuction() ارسال شده است) باید دارای تابع scoreAd() باشد. این یک بار برای هر تبلیغ اجرا می شود تا مطلوبیت آن مشخص شود.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

scoreAd() آرگومان های زیر را می گیرد:

adMetadata
ابرداده خودسرانه ارائه شده توسط خریدار.
bid
یک ارزش پیشنهادی عددی
auctionConfig
شیء پیکربندی مزایده به navigator.runAdAuction() ارسال شد.
trustedScoringSignals
مقادیر بازیابی شده در زمان حراج از سرور مورد اعتماد فروشنده، نشان دهنده نظر فروشنده در مورد آگهی است.
browserSignals
یک شی ساخته شده توسط مرورگر، شامل اطلاعاتی که مرورگر می داند و ممکن است اسکریپت حراج فروشنده بخواهد آن را تأیید کند:

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

قبل از شروع حراج، فروشنده بهترین آگهی متنی را برای جایگاه آگهی موجود پیدا می کند. بخشی از منطق scoreAd() آن رد هر تبلیغی است که نتواند برنده متنی را شکست دهد.

5. فروشنده و خریداران شرکت کننده داده های بیدرنگ را از سرویس کلید/ارزش دریافت می کنند

تصویری که شخصی را در حال مشاهده یک وب سایت خبری در مرورگر لپ تاپ خود نشان می دهد. یک مزایده تبلیغاتی با استفاده از API مخاطب محافظت شده در حال انجام است و یک شرکت‌کننده داده‌ها را از سرویس کلید/ارزش دریافت می‌کند.

بخش توضیح دهنده: واکشی داده های بلادرنگ از سرویس کلید/مقدار مخاطب محافظت شده .

در طول یک حراج تبلیغاتی، فروشنده فضای تبلیغاتی می‌تواند با درخواست به یک سرویس کلید/مقدار با استفاده از ویژگی trustedScoringSignalsUrl آرگومان پیکربندی حراج به navigator.runAdAuction() ، داده‌های بی‌درنگ درباره خلاقیت‌های تبلیغاتی خاص دریافت کند، همراه با کلیدهایی از ویژگی‌های renderUrl همه ورودی‌ها در قسمت‌های ads و اجزای adComponents همه گروه‌های ذینفع در حراج.

به همین ترتیب، یک خریدار فضای تبلیغاتی می‌تواند با استفاده از ویژگی‌های trustedBiddingSignalsUrl و trustedBiddingSignalsKeys از navigator.joinAdInterestGroup() گروه علاقه، داده‌های بلادرنگ را از سرویس Key/Value درخواست کند.

هنگامی که runAdAuction() فراخوانی می شود، مرورگر درخواستی را به سرور مورد اعتماد هر خریدار آگهی ارسال می کند. URL درخواست ممکن است به این صورت باشد:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2

URL پایه از trustedBiddingSignalsUrl می آید.
hostname توسط مرورگر ارائه شده است.
مقدار keys از trustedBiddingSignalsKeys گرفته شده است.

پاسخ به این درخواست یک شی JSON است که مقادیری را برای هر یک از کلیدها ارائه می دهد.

نکته کلیدی: در مرحله آزمایشی اولیه فعلی برای آزمایش مخاطبین محافظت‌شده، trustedBiddingSignalsUrl باید منشأ یکسانی با مالک گروه ذینفع داشته باشد: به ویژگی‌های گروه علاقه و Bring Your Own Server مراجعه کنید.

6. آگهی برنده نمایش داده می شود

تصویری که شخصی را در حال مشاهده یک وب سایت خبری در مرورگر لپ تاپ خود نشان می دهد. یک تبلیغ برای دوچرخه (20٪ تخفیف) نمایش داده می شود - با قفل در بالا برای نشان دادن اینکه تبلیغ در یک قاب حصاردار نمایش داده می شود.

بخش توضیح دهنده: مرورگرها آگهی برنده را ارائه می دهند

همانطور که قبلاً توضیح داده شد: وعده ای که توسط runAdAuction() برگردانده می شود به یک URN که برای رندر به یک قاب حصاردار ارسال می شود حل می شود و سایت آگهی برنده را نمایش می دهد.

7. نتیجه مزایده گزارش می شود

بخش توضیح دهنده: گزارش در سطح رویداد (در حال حاضر)

توجه: برنامه بلندمدت این است که مرورگر را قادر می سازد تا نتایج حراج را با استفاده از APIهای گزارش انبوه برای فروشنده و خریداران گزارش دهد. به عنوان یک مکانیسم گزارش موقت در سطح رویداد، کد پیاده‌سازی reportResult() برای فروشنده، و reportWin() برای پیشنهاد دهنده برنده، می‌توانند تابع sendReportTo() را فراخوانی کنند. این به یک آرگومان واحد نیاز دارد: رشته ای که نشان دهنده یک URL است که پس از اتمام حراج واکشی می شود، که اطلاعات سطح رویداد را برای گزارش کدگذاری می کند.

فروشنده نتیجه را گزارش می دهد

بخش توضیح دهنده: گزارش فروشنده در مورد رندر

جاوا اسکریپت فروشنده ارائه شده در decisionLogicUrl (که همچنین scoreAd() ارائه می کند) می تواند شامل یک تابع reportResult() برای گزارش نتیجه حراج باشد.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

آرگومان های ارسال شده به این تابع عبارتند از:

auctionConfig
شیء پیکربندی مزایده به navigator.runAdAuction() ارسال شد.

browserSignals
یک شی ساخته شده توسط مرورگر که اطلاعات مربوط به حراج را ارائه می دهد. به عنوان مثال:

{
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

مقدار برگشتی این تابع به عنوان آرگومان sellerSignals برای تابع reportWin() پیشنهاد دهنده برنده استفاده می شود.

برنده مناقصه نتیجه را گزارش می دهد

بخش توضیح دهنده: گزارش خریدار در مورد رندر و رویدادهای تبلیغاتی

جاوا اسکریپت برنده مناقصه (که همچنین generateBid() را ارائه می کند) می تواند شامل یک تابع reportWin() برای گزارش نتیجه حراج باشد.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

توجه: اجرای فعلی مخاطبین محافظت شده در کروم در صورتی که reportWin() تعریف نشده باشد هشدار می دهد.

آرگومان های ارسال شده به این تابع عبارتند از:

auctionSignals و perBuyerSignals
همان مقادیر به generateBid() برای مناقصه برنده منتقل می شود.
sellerSignals
مقدار بازگشتی reportResult() که به فروشنده این فرصت را می دهد تا اطلاعات را به خریدار منتقل کند.

browserSignals
یک شی ساخته شده توسط مرورگر که اطلاعات مربوط به حراج را ارائه می دهد. به عنوان مثال:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

اجرای گزارش گیری موقت ضرر/برد

دو روش به طور موقت در Chrome برای گزارش حراج در دسترس است:

forDebuggingOnly.reportAdAuctionLoss()
forDebuggingOnly.reportAdAuctionWin()

این روش‌ها هر کدام یک آرگومان دارند: یک URL برای واکشی پس از اتمام حراج. آنها را می توان چندین بار، هم در scoreAd() و هم generateBid() با آرگومان های URL مختلف فراخوانی کرد.

Chrome فقط زمانی گزارش‌های اشکال‌زدایی از دست دادن/برنده شدن را ارسال می‌کند که یک مزایده کامل شود. اگر حراجی لغو شود (مثلاً به دلیل یک پیمایش جدید) هیچ گزارشی تولید نخواهد شد.

این روش ها به صورت پیش فرض در کروم موجود هستند. برای اینکه بتوانید روش‌ها را آزمایش کنید، همه APIهای حریم خصوصی تبلیغات را در chrome://settings/adPrivacy فعال کنید. اگر Chrome را با پرچم‌های خط فرمان اجرا می‌کنید تا مخاطبان محافظت شده را فعال کنید، باید صراحتاً روش‌ها را با اضافه کردن پرچم BiddingAndScoringDebugReportingAPI فعال کنید. اگر پرچم فعال نباشد، روش ها همچنان در دسترس خواهند بود اما کاری انجام نمی دهند.

8. یک کلیک آگهی گزارش می شود

تصویری که فردی را نشان می‌دهد که روی یک آگهی دوچرخه، داخل یک قاب حصاردار، در یک وب‌سایت خبری کلیک می‌کند و داده‌های گزارش به فروشنده و خریداران می‌رسد.

یک کلیک بر روی یک تبلیغ ارائه شده در یک قاب حصاردار گزارش می شود. برای کسب اطلاعات بیشتر در مورد نحوه عملکرد این کار، به گزارش تبلیغات قاب های حصاردار مراجعه کنید.

نمودار زیر هر مرحله از حراج تبلیغات مخاطب محافظت شده را نشان می دهد:

تصویری که نمای کلی هر مرحله از حراج تبلیغات مخاطب محافظت شده را ارائه می دهد

تفاوت بین مخاطبان محافظت شده و TURTLEDOVE چیست؟

مخاطب محافظت شده اولین آزمایشی است که در Chromium در خانواده پیشنهادات TURTLEDOVE اجرا شده است.

مخاطب محافظت شده از اصول سطح بالای TURTLEDOVE پیروی می کند. برخی از تبلیغات آنلاین مبتنی بر نشان دادن تبلیغ به یک شخص بالقوه با علاقه است که قبلاً با تبلیغ کننده یا شبکه تبلیغاتی تعامل داشته است. از نظر تاریخی این کار توسط تبلیغ کننده به رسمیت شناختن یک شخص خاص در هنگام مرور در وب سایت ها ، یک نگرانی اصلی در مورد حریم خصوصی با وب امروز کار کرده است.

تلاش TURTLEDOVE در مورد ارائه یک API جدید برای رسیدگی به این مورد استفاده و در عین حال ارائه برخی از پیشرفت‌های کلیدی حفظ حریم خصوصی است:

مرورگر ، نه تبلیغ کننده ، اطلاعات مربوط به آنچه را که تبلیغ کننده فکر می کند شخص به آن علاقه مند است ، در اختیار دارد.
تبلیغ کنندگان می توانند بر اساس علاقه ، تبلیغات را انجام دهند ، اما نمی توانند این علاقه را با سایر اطلاعات مربوط به شخص - به ویژه ، آنها چه کسانی هستند یا چه صفحه ای را بازدید می کنند ، ترکیب کنند.

مخاطبان محافظت شده از Turtledove و مجموعه ای از پیشنهادات مرتبط برای اصلاحات برای ارائه خدمات بهتر به توسعه دهندگان که از API استفاده می کنند ، رشد کردند:

در SPARROW : Criteo اضافه کردن یک مدل سرویس ("Gatekeeper") را پیشنهاد کرد که در یک محیط اجرای قابل اعتماد (TEE) اجرا می شود. مخاطبان محافظت شده شامل استفاده محدودتر از TEES ، برای جستجوی داده های در زمان واقعی و گزارش های جمع شده است.
پیشنهادهای NextRoll TERN و Magnite's PARRROT نقش های متفاوتی را که خریداران و فروشندگان در حراج روی دستگاه داشتند، تشریح کردند. جریان مناقصه/امتیاز دهی مخاطبان محافظت شده براساس این کار است.
تغییرات TURTLEDOVE مبتنی بر نتیجه و در سطح محصول RTB House، مدل ناشناس بودن و قابلیت‌های شخصی‌سازی حراج روی دستگاه را بهبود بخشید.
Parakeet پیشنهاد مایکروسافت برای یک سرویس تبلیغاتی شبیه به لاک پشت است که به یک سرور پروکسی متکی است که در یک مرورگر و ارائه دهندگان ADTech در حال اجرا است ، تا درخواست های تبلیغاتی را ناشناس کند و خصوصیات حریم خصوصی را اجرا کند. مخاطبان محافظت شده این مدل پروکسی را اتخاذ نکرده اند. ما در حمایت از کار آینده برای ترکیب بیشتر بهترین ویژگی های هر دو پیشنهاد ، API های JavaScript را برای Parakeet و محافظت از مخاطبان محافظت می کنیم.

مخاطبان محافظت شده هنوز مانع از یادگیری شبکه تبلیغاتی یک وب سایت نمی شوند که یک شخص را می بیند. ما انتظار داریم API را تغییر دهیم تا در طول زمان خصوصی تر شود.

چه پیکربندی مرورگر موجود است؟

کاربران می‌توانند با فعال یا غیرفعال کردن تنظیمات سطح بالا در chrome://settings/adPrivacy مشارکت خود را برای آزمایش‌های جعبه ایمنی حریم خصوصی در Chrome تنظیم کنند. در حین آزمایش اولیه ، افراد قادر خواهند بود از این تنظیمات ماسه ای حریم خصوصی سطح بالا برای امتناع از مخاطبان محافظت شده استفاده کنند. Chrome قصد دارد به کاربران اجازه دهد لیست گروه های ذینفع را که به آنها در وب سایت هایی که از آنها بازدید کرده اند اضافه کرده و مدیریت کنند. همانند خود فناوری‌های جعبه ایمنی حریم خصوصی، تنظیمات کاربر ممکن است با بازخورد کاربران، تنظیم‌کننده‌ها و دیگران تغییر کند.

با پیشرفت پیشنهاد مخاطبان محافظت شده ، بر اساس تست ها و بازخورد ، ما به روزرسانی های موجود در Chrome را به روز خواهیم کرد. در آینده ، ما قصد داریم تنظیمات گرانول بیشتری را برای مدیریت مخاطبان محافظت شده و داده های مرتبط ارائه دهیم.

تماس گیرندگان API وقتی کاربران در حالت ناشناس مرور می کنند ، نمی توانند به عضویت گروه دسترسی پیدا کنند و وقتی کاربران داده های سایت خود را پاک می کنند ، عضویت حذف می شوند.

بازخورد را درگیر و به اشتراک بگذارید

GitHub : پیشنهاد را بخوانید ، سؤالات را مطرح کنید و بحث را دنبال کنید .
W3C : در مورد موارد استفاده از صنعت در بهبود گروه تجاری تبلیغات وب بحث کنید.
پشتیبانی برنامه‌نویس : سؤال بپرسید و به بحث‌های مربوط به مخزن پشتیبانی توسعه‌دهنده Privacy Sandbox بپیوندید.
لیست پستی Fledge : Fledge-Api-Annound اطلاعیه ها و به روزرسانی هایی را در مورد API ارائه می دهد.
به تماس های برنامه ریزی شده برای مخاطبان محافظت شده (هر هفته دوم) بپیوندید . همه از پیوستن به آنها استقبال می کنند - برای شرکت در آن ، ابتدا حتماً به WICG بپیوندید . شما می توانید فعالانه شرکت کنید یا فقط به آن گوش دهید!
از فرم بازخورد Sandbox حریم خصوصی برای به اشتراک گذاشتن بازخورد به صورت خصوصی با تیم Chrome در خارج از انجمن های عمومی استفاده کنید.

پشتیبانی دریافت کنید

برای پرسیدن سوالی در مورد اجرای خود ، در مورد نسخه ی نمایشی یا اسناد :

مسئله جدیدی را در مورد مخزن حریم خصوصی Sandbox-DEV پشتیبانی کنید . حتماً الگوی مسئله را برای مخاطبان محافظت شده انتخاب کنید.
مسئله ای را در مورد repo کد نسخه ی نمایشی در GitHub مطرح کنید.
برای سؤالات کلی تر در مورد چگونگی پاسخگویی به موارد استفاده خود با API ، در مورد مخزن پیشنهاد ، مسئله ای را مطرح کنید .

برای اشکالات و مشکلات مربوط به اجرای API مخاطبان محافظت شده در Chrome: * موضوعات موجود گزارش شده برای API را مشاهده کنید . * شماره جدیدی را در crbug.com/new مطرح کنید.

دریافت به روز رسانی

برای اطلاع از تغییرات وضعیت در API ، به لیست پستی برای توسعه دهندگان بپیوندید.
برای پیگیری نزدیک تمام بحث های در حال انجام در مورد API ، روی دکمه Watch در صفحه پیشنهاد در GitHub کلیک کنید. این امر به شما نیاز دارد یا یک حساب GitHub ایجاد کنید .
برای به دست آوردن به روزرسانی های کلی در مورد حریم خصوصی حریم خصوصی ، در FEED RSS [پیشرفت در ماسهبازی حریم خصوصی] مشترک شوید.

بیشتر بدانید

API مخاطبان محافظت شده : نمای کلی فنی کمتر از این پیشنهاد.
نسخه نمایشی مخاطبان محافظت شده : پیاده روی از استقرار اساسی مخاطبان محافظت شده.
ویدیوی نسخه ی نمایشی مخاطبان محافظت شده : کد نسخه ی نمایشی را توضیح می دهد ، و نحوه استفاده از Devtools Chrome را برای اشکال زدایی مخاطبان محافظت شده نشان می دهد.
مخاطبان محافظت شده API فنی توضیح دهنده
حفر داخل ماسه صندوق حریم خصوصی
قصد نمونه اولیه

عکس توسط ری هنسی در Unsplash .

راهنمای توسعه دهنده FLEDGE API

این مقاله برای چه کسانی است؟

مخاطب محافظت شده چیست؟

چگونه می توانم مخاطب محافظت شده را امتحان کنم؟

نسخه ی نمایشی مخاطبان محافظت شده

در آزمایشی مبدأ مخاطب محافظت شده شرکت کنید

این API را تست کنید

تبلیغات را در iframe یا قاب های حصاردار ارائه دهید

چه ویژگی هایی در آخرین نسخه کروم پشتیبانی می شود؟

مجوزهای گروه علاقه

خدمات کلید/ارزش

شناسایی پشتیبانی از ویژگی ها

چگونه می توانم از مخاطبین محافظت شده انصراف دهم؟

چگونه سایت ها می توانند دسترسی را کنترل کنند؟

انصراف کاربر

اشکال زدایی ورکلت های مخاطب محافظت شده

رویدادهای مخاطب محافظت شده را مشاهده کنید

API مخاطب محافظت شده چگونه کار می کند؟

1. کاربر از سایت تبلیغ کننده بازدید می کند

2. از مرورگر کاربر خواسته می شود که یک گروه علاقه مندی را اضافه کند

مجوز از سایت در حال بازدید

اجازه از صاحب گروه ذینفع

با استفاده از navigator.joinAdInterestGroup()

خواص گروه بهره

ویژگی های گروه علاقه را به روز کنید

به روز رسانی های دستی

به روز رسانی خودکار

تبلیغات را برای یک گروه علاقه مند مشخص کنید

خریداران چگونه پیشنهاد می دهند؟

درخواست از یک مرورگر برای ترک یک گروه علاقه مند

3. کاربر از سایتی بازدید می کند که فضای تبلیغاتی را می فروشد

4. یک مزایده تبلیغاتی در مرورگر اجرا می شود

خواص auctionConfig

تبلیغات چگونه انتخاب می شوند؟

5. فروشنده و خریداران شرکت کننده داده های بیدرنگ را از سرویس کلید/ارزش دریافت می کنند

6. آگهی برنده نمایش داده می شود

7. نتیجه مزایده گزارش می شود

فروشنده نتیجه را گزارش می دهد

برنده مناقصه نتیجه را گزارش می دهد

اجرای گزارش گیری موقت ضرر/برد

8. یک کلیک آگهی گزارش می شود

تفاوت بین مخاطبان محافظت شده و TURTLEDOVE چیست؟

چه پیکربندی مرورگر موجود است؟

بازخورد را درگیر و به اشتراک بگذارید

پشتیبانی دریافت کنید

دریافت به روز رسانی

بیشتر بدانید

خواص `auctionConfig`