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

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

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

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

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

برای اطلاع از تغییرات وضعیت در API، به لیست پستی توسعه دهندگان بپیوندید.

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

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

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

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

مرجع API موجود

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

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

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

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

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

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

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

تبلیغات را در 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 مخاطب محافظت شده خریدار خواهد بود. عضویت در گروه علاقه‌مندی توسط مرورگر، در دستگاه کاربر ذخیره می‌شود و با فروشنده مرورگر یا شخص دیگری به اشتراک گذاشته نمی‌شود.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تفاوت بین 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 برای کنترل رفتار کش استفاده کنید.

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

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

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

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

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

انصراف دهید

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

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