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

راهنمای برنامه‌نویس برای مزایده‌های تبلیغاتی روی دستگاه برای ارائه خدمات به بازاریابی مجدد و مخاطبان سفارشی، بدون ردیابی شخص ثالث بین سایتی.

برای کسانی که تازه با Protected Audience API آشنا شده‌اند، نمای کلی Protected Audience API را برای توضیح سطح بالای API بخوانید.

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

وضعیت پیاده سازی

• The Protected Audience API proposal is now moving to general availability. Raise questions and follow discussion.
• Protected Audience API status of pending capabilities details changes and enhancements to the Protected Audience API API and features.
• Blink status
• Protected Audience API Chrome platform status: Specific to the Protected Audience API on Chrome.
• Ads API Chrome platform status: A collection of APIs to facilitate advertising: Protected Audience API, Topics, Fenced Frames and Attribution Reporting.

To be notified of status changes in the API, join the mailing list for developers.

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

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

Protected Audience API اولین آزمایشی است که در Chromium در خانواده پیشنهادات TURTLEDOVE اجرا شده است.

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

مرجع API موجود

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

• راهنمای خریداران برای joinAdInterestGroup() و generateBid() .
• راهنمای فروشنده برای API مخاطب محافظت شده runAdAuction()
• راهنمای خریداران برای reportWin() و راهنمای فروشندگان برای reportResult()
• عیب یابی Protected Audience API

همچنین می‌توانید بهترین شیوه‌های تأخیر آگهی مزایده API مخاطبین محافظت‌شده را بخوانید.

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

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

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

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

• همه APIهای حریم خصوصی تبلیغات را در chrome://settings/adPrivacy فعال کنید.
• پرچم ها را از خط فرمان تنظیم کنید . فهرست کامل پرچم‌های API مخاطب محافظت‌شده موجود را می‌توانید در جستجوی کد Chromium پیدا کنید.

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

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

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

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

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

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

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

ویژگی های پشتیبانی شده

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

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

درباره پشتیبانی از ویژگی ها و محدودیت ها در توضیح API مخاطب محافظت شده بیشتر بخوانید.

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

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

در آینده، هنگامی که صاحبان سایت فرصت داشتند تا خط‌مشی‌های مجوزهای iframe بین دامنه‌ای خود را به‌روزرسانی کنند، برنامه این است که تماس‌ها از iframe بین دامنه‌ای مجاز نباشد.

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

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

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

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

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

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

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

قبل از استفاده از 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 مخاطب محافظت شده چگونه کار می کند؟

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

ویژگی‌های Protected Audience API به مرور زمان با پیشرفت کار روی پیاده‌سازی اضافه می‌شوند.

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

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

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

پلتفرم سمت تقاضای تبلیغ‌کننده (DSP) (یا خود تبلیغ‌کننده) navigator.joinAdInterestGroup() را فرا می‌خواند تا از مرورگر بخواهد یک گروه علاقه‌مند را به لیست گروه‌هایی که مرورگر در آن عضو است اضافه کند.

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

• توضیح دهنده API مخاطب محافظت شده را بخوانید : مرورگرها گروه های علاقه را ثبت می کنند .
• راهنمای API را بخوانید : خریداران و DSPها، یاد بگیرید که چگونه به joinAdInterestGroup() و پیشنهادات را ایجاد کنید.

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

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

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

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

generateBid() برای هر گروه ذینفعی که مرورگر عضوی از آن است فراخوانی می‌شود—اگر مالک گروه علاقه‌مند به پیشنهاد دعوت شود.

مستندات توسعه دهنده generatedBid() بخوانید.

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

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

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

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

• توضیح دهنده API مخاطب محافظت شده را بخوانید : فروشندگان مزایده های روی دستگاه را اجرا می کنند
• راهنمای API را بخوانید : فروشندگان می‌توانند درباره runAdAuction() و بهترین شیوه‌های تاخیر حراج آگهی اطلاعات بیشتری کسب کنند.

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

در طول یک حراج آگهی، فروشنده می‌تواند با ارسال درخواست به سرویس کلید/ارزش خود، داده‌های بی‌درنگ درباره خلاقیت‌های تبلیغاتی خاص درخواست کند. فروشنده می‌تواند این اطلاعات را در طول runAdAuction() توسط ویژگی trustedScoringSignalsUrl به همراه کلیدهای ویژگی‌های 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 است که مقادیری را برای هر یک از کلیدها ارائه می دهد.

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

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

زمانی که پرچم ()runAdAuction بر روی یک شیء پیکربندی قاب محصور شده ( FencedFrameConfig ) برگردانده می شود، زمانی که پرچم resolveToConfig روی true در پیکربندی حراج تنظیم شود. پیکربندی فریم توسط یک قاب حصاردار برای پیمایش قاب به سمت تبلیغ برنده استفاده می‌شود، اما URL آگهی برای جاسازی قاب قابل مشاهده نیست.

شیء پیکربندی قاب حصاردار از M114 در دسترس است. برای اطلاعات بیشتر در مورد شی FencedFrameConfig ، مقاله وبلاگ Chrome را ببینید.

• توضیح دهنده API مخاطب محافظت شده را بخوانید : مرورگرها آگهی برنده را ارائه می دهند

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

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

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

• راهنمای API را بخوانید : درباره گزارش‌دهی فروشنده و خریدار بیاموزید

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

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

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

Protected Audience API اولین آزمایشی است که در Chromium در خانواده پیشنهادات TURTLEDOVE اجرا شده است.

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

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

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

Protected Audience API از TURTLEDOVE و مجموعه‌ای از پیشنهادات مرتبط برای تغییرات ایجاد شد تا به توسعه‌دهندگانی که از API استفاده می‌کنند، خدمات بهتری ارائه دهد:

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

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

آیا می توان از Topics API با API مخاطبان محافظت شده استفاده کرد؟

بله یک موضوع مشاهده شده برای کاربر فعلی، ارائه شده توسط Topics API ، می تواند به عنوان اطلاعات متنی توسط فروشنده یا پیشنهاد دهنده استفاده شود. یک موضوع می تواند در ویژگی های زیر گنجانده شود:

• auctionSignals ، یک ویژگی شی پیکربندی مزایده است که به navigator.runAdAuction() ارسال شده است.
• userBiddingSignals ، یک ویژگی از شی پیکربندی گروه علاقه که به navigator.joinAdInterestGroup() منتقل می شود.

پیکربندی مرورگر موجود

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

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

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

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

آیا Worklet های مخاطب محافظت شده توسط مرورگر ذخیره می شوند؟

منابعی که شامل Worklet های مخاطب محافظت شده است - کارنامه تولید پیشنهاد خریدار و گزارش کار، و امتیازدهی آگهی و کارنامه گزارش فروشنده - توسط مرورگر ذخیره می شوند. می توانید از هدر Cache-Control برای کنترل رفتار کش استفاده کنید.

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

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

برای پرسیدن سوال و دریافت پشتیبانی با پیاده سازی، نسخه آزمایشی یا مستندات:

• GitHub : توضیح دهنده را بخوانید، سوالاتی را مطرح کنید و بحث را دنبال کنید .
• نسخه ی نمایشی : مشکلی را در مخزن کد نسخه ی نمایشی مطرح کنید.
• پشتیبانی برنامه‌نویس : سؤال بپرسید و به بحث‌های مربوط به مخزن پشتیبانی توسعه‌دهنده Privacy Sandbox بپیوندید. الگوی مشکل را برای API مخاطب محافظت شده انتخاب کنید.
• پیاده‌سازی Chrome : برای اشکالات یا مشکلات مربوط به اجرای Chrome از مخاطبین محافظت‌شده API، می‌توانید مشکلات موجود را مشاهده کنید یا مشکل جدیدی را مطرح کنید .

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

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

انصراف دهید

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

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

• برای اطلاع از تغییرات وضعیت API، به لیست پستی توسعه دهندگان بپیوندید.
• برای پیگیری دقیق همه بحث‌های جاری در API، روی دکمه Watch در صفحه API در GitHub کلیک کنید. برای این کار باید یک حساب GitHub داشته باشید یا ایجاد کنید .
• برای دریافت به‌روزرسانی‌های کلی در مورد جعبه ایمنی حریم خصوصی، در فید RSS [پیشرفت در جعبه ایمنی حریم خصوصی] مشترک شوید.
• به تماس‌های برنامه‌ریزی‌شده برای API مخاطب محافظت‌شده (هر هفته دوم) بپیوندید . از همه برای پیوستن خوش آمدید - برای شرکت، ابتدا مطمئن شوید که به WICG بپیوندید . شما می توانید فعالانه شرکت کنید یا فقط به آن گوش دهید!

راهنمای برنامه‌نویس برای مزایده‌های تبلیغاتی روی دستگاه برای ارائه خدمات به بازاریابی مجدد و مخاطبان سفارشی، بدون ردیابی شخص ثالث بین سایتی.

برای کسانی که تازه با Protected Audience API آشنا شده‌اند، نمای کلی Protected Audience API را برای توضیح سطح بالای API بخوانید.

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

وضعیت پیاده سازی

• The Protected Audience API proposal is now moving to general availability. Raise questions and follow discussion.
• Protected Audience API status of pending capabilities details changes and enhancements to the Protected Audience API API and features.
• Blink status
• Protected Audience API Chrome platform status: Specific to the Protected Audience API on Chrome.
• Ads API Chrome platform status: A collection of APIs to facilitate advertising: Protected Audience API, Topics, Fenced Frames and Attribution Reporting.

To be notified of status changes in the API, join the mailing list for developers.

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

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

Protected Audience API اولین آزمایشی است که در Chromium در خانواده پیشنهادات TURTLEDOVE اجرا شده است.

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

مرجع API موجود

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

• راهنمای خریداران برای joinAdInterestGroup() و generateBid() .
• راهنمای فروشنده برای API مخاطب محافظت شده runAdAuction()
• راهنمای خریداران برای reportWin() و راهنمای فروشندگان برای reportResult()
• عیب یابی Protected Audience API

همچنین می‌توانید بهترین شیوه‌های تأخیر آگهی مزایده API مخاطبین محافظت‌شده را بخوانید.

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

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

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

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

• همه APIهای حریم خصوصی تبلیغات را در chrome://settings/adPrivacy فعال کنید.
• پرچم ها را از خط فرمان تنظیم کنید . فهرست کامل پرچم‌های API مخاطب محافظت‌شده موجود را می‌توانید در جستجوی کد Chromium پیدا کنید.

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

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

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

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

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

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

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

ویژگی های پشتیبانی شده

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

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

درباره پشتیبانی از ویژگی ها و محدودیت ها در توضیح API مخاطب محافظت شده بیشتر بخوانید.

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

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

در آینده، هنگامی که صاحبان سایت فرصت داشتند تا خط‌مشی‌های مجوزهای iframe بین دامنه‌ای خود را به‌روزرسانی کنند، برنامه این است که تماس‌ها از iframe بین دامنه‌ای مجاز نباشد.

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

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

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

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

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

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

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

قبل از استفاده از 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 مخاطب محافظت شده چگونه کار می کند؟

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

ویژگی‌های Protected Audience API به مرور زمان با پیشرفت کار روی پیاده‌سازی اضافه می‌شوند.

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

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

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

پلتفرم سمت تقاضای تبلیغ‌کننده (DSP) (یا خود تبلیغ‌کننده) navigator.joinAdInterestGroup() را فرا می‌خواند تا از مرورگر بخواهد یک گروه علاقه‌مند را به لیست گروه‌هایی که مرورگر در آن عضو است اضافه کند.

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

• توضیح دهنده API مخاطب محافظت شده را بخوانید : مرورگرها گروه های علاقه را ثبت می کنند .
• راهنمای API را بخوانید : خریداران و DSPها، یاد بگیرید که چگونه به joinAdInterestGroup() و پیشنهادات را ایجاد کنید.

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

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

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

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

generateBid() برای هر گروه ذینفعی که مرورگر عضوی از آن است فراخوانی می‌شود—اگر مالک گروه علاقه‌مند به پیشنهاد دعوت شود.

مستندات توسعه دهنده generatedBid() بخوانید.

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

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

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

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

• توضیح دهنده API مخاطب محافظت شده را بخوانید : فروشندگان مزایده های روی دستگاه را اجرا می کنند
• راهنمای API را بخوانید : فروشندگان می‌توانند درباره runAdAuction() و بهترین شیوه‌های تاخیر حراج آگهی اطلاعات بیشتری کسب کنند.

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

در طول یک حراج آگهی، فروشنده می‌تواند با ارسال درخواست به سرویس کلید/ارزش خود، داده‌های بی‌درنگ درباره خلاقیت‌های تبلیغاتی خاص درخواست کند. فروشنده می‌تواند این اطلاعات را در طول runAdAuction() توسط ویژگی trustedScoringSignalsUrl به همراه کلیدهای ویژگی‌های 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 است که مقادیری را برای هر یک از کلیدها ارائه می دهد.

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

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

زمانی که پرچم ()runAdAuction بر روی یک شیء پیکربندی قاب محصور شده ( FencedFrameConfig ) برگردانده می شود، زمانی که پرچم resolveToConfig روی true در پیکربندی حراج تنظیم شود. پیکربندی فریم توسط یک قاب حصاردار برای پیمایش قاب به سمت تبلیغ برنده استفاده می‌شود، اما URL آگهی برای جاسازی قاب قابل مشاهده نیست.

شیء پیکربندی قاب حصاردار از M114 در دسترس است. برای اطلاعات بیشتر در مورد شی FencedFrameConfig ، مقاله وبلاگ Chrome را ببینید.

• توضیح دهنده API مخاطب محافظت شده را بخوانید : مرورگرها آگهی برنده را ارائه می دهند

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

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

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

• راهنمای API را بخوانید : درباره گزارش‌دهی فروشنده و خریدار بیاموزید

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

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

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

Protected Audience API اولین آزمایشی است که در Chromium در خانواده پیشنهادات TURTLEDOVE اجرا شده است.

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

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

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

Protected Audience API از TURTLEDOVE و مجموعه‌ای از پیشنهادات مرتبط برای تغییرات ایجاد شد تا به توسعه‌دهندگانی که از API استفاده می‌کنند، خدمات بهتری ارائه دهد:

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

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

آیا می توان از Topics API با API مخاطبان محافظت شده استفاده کرد؟

بله یک موضوع مشاهده شده برای کاربر فعلی، ارائه شده توسط Topics API ، می تواند به عنوان اطلاعات متنی توسط فروشنده یا پیشنهاد دهنده استفاده شود. یک موضوع می تواند در ویژگی های زیر گنجانده شود:

• auctionSignals ، یک ویژگی از شی پیکربندی حراج به navigator.runAdAuction()
• userBiddingSignals ، یک ویژگی از شی پیکربندی گروه علاقه که به navigator.joinAdInterestGroup() ارسال می شود.

پیکربندی مرورگر موجود

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

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

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

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

آیا Worklet های مخاطب محافظت شده توسط مرورگر ذخیره می شوند؟

منابعی که شامل Worklet های مخاطب محافظت شده است - کارنامه تولید پیشنهاد خریدار و گزارش کار، و امتیازدهی آگهی و کارنامه گزارش فروشنده - توسط مرورگر ذخیره می شوند. می توانید از هدر Cache-Control برای کنترل رفتار کش استفاده کنید.

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

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

برای پرسیدن سوال و دریافت پشتیبانی با پیاده سازی، نسخه آزمایشی یا مستندات:

• GitHub : توضیح دهنده را بخوانید، سوالاتی را مطرح کنید و بحث را دنبال کنید .
• نسخه ی نمایشی : مشکلی را در مخزن کد نسخه ی نمایشی مطرح کنید.
• پشتیبانی برنامه‌نویس : سؤال بپرسید و به بحث‌های مربوط به مخزن پشتیبانی توسعه‌دهنده Privacy Sandbox بپیوندید. الگوی مشکل را برای API مخاطب محافظت شده انتخاب کنید.
• پیاده‌سازی Chrome : برای اشکالات یا مشکلات مربوط به اجرای Chrome از مخاطبین محافظت‌شده API، می‌توانید مشکلات موجود را مشاهده کنید یا مشکل جدیدی را مطرح کنید .

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

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

انصراف دهید

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

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

• برای اطلاع از تغییرات وضعیت API، به لیست پستی توسعه دهندگان بپیوندید.
• برای پیگیری دقیق همه بحث‌های جاری در API، روی دکمه Watch در صفحه API در GitHub کلیک کنید. برای این کار باید یک حساب GitHub داشته باشید یا ایجاد کنید .
• برای دریافت به‌روزرسانی‌های کلی در مورد جعبه ایمنی حریم خصوصی، در فید RSS [پیشرفت در جعبه ایمنی حریم خصوصی] مشترک شوید.
• به تماس‌های برنامه‌ریزی‌شده برای API مخاطب محافظت‌شده (هر هفته دوم) بپیوندید . از همه برای پیوستن خوش آمدید - برای شرکت، ابتدا مطمئن شوید که به WICG بپیوندید . شما می توانید فعالانه شرکت کنید یا فقط به آن گوش دهید!