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

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

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

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

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

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

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

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

رابط برنامه‌نویسی کاربردی مخاطبان محافظت‌شده (Protected Audience API) اولین آزمایشی است که در کرومیوم و در چارچوب خانواده‌ی پیشنهادهای TURTLEDOVE پیاده‌سازی می‌شود.

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

مرجع API موجود

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

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

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

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

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

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

شما می‌توانید API مخاطب محافظت‌شده را برای یک کاربر در کروم بتا ۱۰۱.۰.۴۹۵۱.۲۶ و بالاتر روی دسکتاپ آزمایش کنید:

نمایش تبلیغات در iframe یا قاب‌های حصارکشی شده

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

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

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

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

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

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

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

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

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

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

مجوزهای گروه‌های ذینفع

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

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

سرویس کلید/مقدار

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مستندات توسعه‌دهنده‌ی generatedBid() را مطالعه کنید.

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

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

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

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

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

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

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

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

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

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

۶. تبلیغ برنده نمایش داده می‌شود

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

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

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

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

برنامه بلندمدت این است که به مرورگر اجازه داده شود با استفاده از APIهای Private Aggregation، نتایج حراج را برای فروشنده و خریدار گزارش دهد.

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

۸. کلیک روی تبلیغ گزارش شده است

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

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

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

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

رابط برنامه‌نویسی کاربردی مخاطبان محافظت‌شده (Protected Audience API) اولین آزمایشی است که در کرومیوم و در چارچوب خانواده‌ی پیشنهادهای TURTLEDOVE پیاده‌سازی می‌شود.

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

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

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

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

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

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

آیا می‌توان از API موضوعات (Topics API) به همراه API مخاطبان محافظت‌شده (Protected Audience API) استفاده کرد؟

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

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

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

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

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

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

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

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

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

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

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

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

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

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

انصراف

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

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