گزارش حراج API مخاطب محافظت شده

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

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

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

  • جمع آوری خصوصی که سیگنال ها و نتایج حراج را برای تولید گزارش های خلاصه جمع آوری می کند.
  • Ads Reporting API for Fenced Frames و iframes که کانالی در داخل فریم ها برای ارتباط با Worklet های API مخاطب محافظت شده است. API اجازه می دهد تا داده های سطح رویداد را با سیگنال های حراج مرتبط کنیم. گزارش‌دهی در سطح رویداد Ads Reporting API یک مکانیسم انتقالی است تا زمانی که مکانیزم گزارش‌دهی خصوصی‌تر طراحی شود.
  • Attribution Reporting که به شما امکان می دهد داده های تبدیل را با سیگنال های حراج مرتبط کنید.
  • فضای ذخیره‌سازی مشترک که به شما امکان می‌دهد سیگنال‌های حراج را در فضای ذخیره‌سازی متقاطع بنویسید، سپس به شما امکان می‌دهد آن داده‌ها را بعداً با استفاده از تجمیع خصوصی گزارش دهید.

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

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

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

در طول زمان حراج، می توانید داده های حراج را با استفاده از کارنامه های گزارش دهی گزارش دهید. در طول زمان رندر، می‌توانید داده‌های تعامل را از یک iframe یا یک قاب حصاردار گزارش کنید. در طول زمان تبدیل، می توانید داده های انتساب را از صفحه مقصد با استفاده از Attribution Reporting API گزارش دهید.

گزارش مکان ها

در یک حراج، خریداران می‌توانند سیگنال‌های موجود در worklets generateBid() و reportWin() را گزارش کنند، و فروشندگان می‌توانند سیگنال‌های موجود در scoreAd() و reportResult() را گزارش کنند. خارج از حراج، خریداران و فروشندگان می توانند داده ها را از فریمی که آگهی را ارائه کرده و از سایتی که تبدیل از آن انجام شده است، گزارش دهند.

دوره زمانی مقصد مکان داده های موجود APIهای گزارش دهی موجود است
حراج خریدار generateBid() سیگنال ها، نتایج حراج و عملکرد حراج Private Aggregation API
reportWin() Private Aggregation API
API گزارش تبلیغات
فروشنده scoreAd() Private Aggregation API
reportResult() Private Aggregation API
API گزارش تبلیغات
رندر کنید خریدار / فروشنده قاب در سایت ناشر داده‌های سطح رویداد در چارچوب تبلیغات Private Aggregation API
API گزارش تبلیغات
تبدیل خریدار / فروشنده سایت تبدیل داده های تبدیل و سطح رویداد از سایت تبدیل Attribution Reporting API
Private Aggregation API
API گزارش تبلیغات

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

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

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

سیگنال ها

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

سیگنال توضیحات مکان را تنظیم کنید کاربران در دسترس بودن
سیگنال های حراج داده های موجود در زمینه محل برگزاری حراج. این داده ها می تواند شامل اطلاعات محتوای صفحه، داده های کاربر شخص اول و موارد دیگر باشد. توسط فروشنده از سایت ناشر در پیکربندی حراج تنظیم شده است. خریدار
فروشنده		 generateBid scoreAd reportWin reportResult
directFromSellerSignals همان داده ها برای auctionSignals ، perBuyerSignals ، sellerSignals اما سیگنال ها تضمین شده است که از فروشنده مشخص شده می آیند. از طریق هدرهای پاسخ HTTP از فروشنده تنظیم کنید خریدار
فروشنده		 generateBid scoreAd reportWin reportResult
سیگنال های مرورگر داده های مختلف ارائه شده توسط مرورگر ( topWindowHostname ، interestGroupOwner ، renderUrl ، adComponents ، biddingDurationMsec ، IGJoinCount ، IGRecency ، modelingSignals ). توسط مرورگر تنظیم شده است. خریدار
فروشنده		 generateBid scoreAd reportWin reportResult
سیگنال های فروشنده سیگنال هایی که برای امتیازدهی آگهی به فروشنده ارائه می شود. توسط فروشنده از سایت ناشر در پیکربندی حراج تنظیم شده است. فروشنده scoreAd
گزارش برد
گزارش نتیجه
trustedScoringSignals سیگنال های بلادرنگ برای امتیازدهی آگهی به فروشنده ارائه می شود. URL توسط فروشنده از سایت ناشر در پیکربندی حراج تنظیم می شود. فروشنده scoreAd report نتیجه
perBuyerSignals داده های متنی حراج به خریداران خاص ارائه می شود. فروشنده می تواند ارزش ها را قبل از شروع حراج برای خریداران بازیابی کند. این دانش خریدار از فرصت تبلیغات است. توسط فروشنده از سایت ناشر در پیکربندی حراج تنظیم شده است. خریدار generateBid scoreAd reportWin reportResult
trustedBiddingSignals سیگنال های بلادرنگ برای مناقصه آگهی به خریداران ارائه می شود. URL توسط خریدار از سایت آگهی‌دهنده تنظیم می‌شود که گروه مورد علاقه تنظیم شود. خریدار ایجاد پیشنهاد قیمت
userBiddingSignals داده های کاربر ارائه شده توسط خریدار. توسط خریدار از سایت آگهی‌دهنده تنظیم می‌شود که گروه علاقه‌مندی تنظیم شود. خریدار ایجاد پیشنهاد قیمت

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

سایر داده های موجود

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

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

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

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

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

گزارش در سطح رویداد

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

گزارش برنده حراج در سطح رویداد با sendReportTo()

مکانیزمی که برای گزارش داده‌های سطح رویداد در حراج مخاطب محافظت‌شده در دسترس است sendReportTo() function در برنده حراج است. این تابع در Workletهای گزارش خریدار و فروشنده موجود است و مرورگر با شروع رندر آگهی، درخواست GET را به رشته URL ارائه شده ارسال می کند. شما می توانید هر سیگنال موجود در Worklet های خود را به عنوان پارامترهای جستجوی URL رمزگذاری کنید.

به عنوان مثال، یک خریدار می‌تواند مبلغ پیشنهادی برنده را از worklet reportWin() برای اهداف صورت‌حساب گزارش کند:

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

تابع sendReportTo() می‌تواند برای تولید یک گزارش برد برای فروشنده هنگام فراخوانی از reportResult() و یک گزارش برد برای خریدار در هنگام فراخوانی از reportWin() استفاده شود. تابع sendReportTo() حداقل تا سال 2026 در دسترس است.

گزارش نامزدی

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

تابع sendReportTo() که در بالا توضیح داده شد می‌تواند برای مرتبط کردن داده‌های حراج با داده‌های سطح رویداد از یک iframe استفاده شود، اما برای یک قاب حصاردار کار نمی‌کند زیرا یک ID منحصربه‌فرد نمی‌تواند از embedder وارد شود، زیرا ارتباط بین embedder و قاب حصارکشی شده محدود است. برای مرتبط کردن داده‌های حراج با داده‌های سطح رویداد از یک آگهی قاب حصاردار، می‌توان از Ads Reporting API استفاده کرد.

API گزارش تبلیغات برای قاب ها و آیفریم های حصاردار

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

در Worklet گزارش‌دهی API Protected Audience، می‌توانید یک چراغ تبلیغاتی را با تابع registerAdBeacon() ثبت کنید و با سیگنال‌هایی که به عنوان پارامترهای پرس و جو اضافه می‌شوند، URL گزارش خود را ارسال کنید. همچنین رویداد سفارشی را که می‌خواهید با URL گزارش‌دهی مرتبط کنید، مشخص می‌کنید. سپس، در زمانی که تبلیغ در یک قاب محصور ارائه می‌شود، می‌توانید با فراخوانی تابع window.fence.reportEvent() ، رویداد سفارشی را فعال کنید. داده های موجود در چارچوب حصارکشی شده را می توان به عنوان محموله اضافه کرد.

تابع registerAdBeacon() فقط در توابع گزارش در دسترس است و در منطق پیشنهاد خریدار و منطق امتیازدهی فروشنده در دسترس نیست.

در مثال زیر، یک شناسه کمپین با یک بارگذاری در سطح رویداد با مختصات کلیک مرتبط است: 

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

Fenced Frames Ads Reporting API نیز حداقل تا سال 2026 به دلایل مشابه گزارش برنده در دسترس خواهد بود.

برای غواصی عمیق تر، توضیح دهنده را ببینید.

دسترسی بدون محدودیت به شبکه

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

دسترسی به شبکه در آینده محدود خواهد شد.

گزارش اسناد

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

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

مکانیسم انتقالی

هنگام ثبت یک چراغ تبلیغاتی، می توانید از کلمه کلیدی reserved.top_navigation استفاده کنید که به طور خودکار سرصفحه Attribution-Reporting-Eligible برای نشان دادن واجد شرایط ثبت نام به عنوان منبع انتساب اضافه می کند.

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

برای پیوست کردن داده‌های سطح رویداد به بیکنی که ثبت کرده‌اید، می‌توانید setReportEventDataForAutomaticBeacons() از قاب حصاردار با بار رویداد فراخوانی کنید.

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

برای کسب اطلاعات بیشتر به بخش Attribution Reporting توضیح Ads Reporting API مراجعه کنید.

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

در این مثال، از دیدگاه خریدار که علاقه مند به مرتبط کردن داده های حراج، فریم آگهی و سایت تبدیل با یکدیگر است، به آن نگاه می کنیم.

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

گردش کار:

  1. قبل از شروع حراج، خریدار یک شناسه منحصربه‌فرد را به عنوان بخشی از پاسخ پیشنهادی پیشنهادی بی‌درنگ برنامه‌ریزی شده ("RTB") برای فروشنده ارسال می‌کند. شناسه را می توان به عنوان متغیری مانند auctionId تنظیم کرد. شناسه به عنوان perBuyerSignals در auctionConfig ارسال می شود و در worklets خریدار در دسترس می شود.
  2. در طول زمان حراج، خریدار می‌تواند یک چراغ تبلیغاتی را ثبت کند تا در زمان رندر آگهی و زمان تبدیل فعال شود ( registerAdBeacon() ).
    1. برای مرتبط کردن سیگنال‌های حراج برای یک رویداد قاب تبلیغاتی، auctionId به‌عنوان پارامتر پرس‌وجو از نشانی اینترنتی بیکن تنظیم کنید.
    2. برای مرتبط کردن سیگنال‌های حراج برای یک رویداد تبدیل، auctionId در نشانی اینترنتی بیکن تنظیم کنید.
  3. در طول زمان رندر آگهی، چراغ‌هایی که در زمان حراج ثبت کرده‌اید می‌توانند با داده‌های سطح رویداد فعال یا تقویت شوند.
    1. رویداد فریم را با reportEvent() فعال کنید و داده های سطح رویداد را ارسال کنید.
    2. با setReportEventDataForAutomaticBeacons() payload در سطح رویداد را به چراغ انتساب اضافه کنید
    3. با پاسخ دادن به درخواست‌های چراغ آگهی با سربرگ Attribution-Reporting-Register-Source آگهی را با API گزارش Attribution ثبت کنید.
  4. در طول زمان تبدیل، می توانید منبعی را که در زمان حراج ثبت کرده اید فعال کنید.

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

گردش کار مشابهی برای فروشنده ای اعمال می شود که نیاز به دسترسی به داده های انتساب داشته باشد، و فروشنده همچنین می تواند از یک شناسه منحصر به فرد برای ارسال با registerAdBeacon() استفاده کند. از فریم، فراخوانی reportEvent() حاوی یک ویژگی مقصد است که می تواند برای ارسال گزارش برای خریدار و فروشنده استفاده شود. توجه داشته باشید که SSP باید در صفحه فرود نیز وجود داشته باشد تا تریگر به منبع نسبت داده شود.

جمع آوری داده های مخاطب محافظت شده

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

به عنوان مثال، یک رویداد نمایش تبلیغات را می توان در سطل های مختلف شمارش کرد، جایی که هر سطل نشان دهنده یک کمپین تبلیغاتی متفاوت است. یک گزارش خلاصه با گزارش سطح رویداد متفاوت است زیرا اطلاعاتی را درباره هر رویداد جداگانه نشان نمی دهد. با یک گزارش در سطح رویداد، می‌توانید تعیین کنید که کاربران A، B و C کمپین 123 را دیده‌اند. با گزارش‌های خلاصه، می‌توانید تعداد کاربرانی را که کمپین 123 را دیده‌اند اندازه‌گیری کنید و نویز برای محافظت از حریم خصوصی کاربر اضافه می‌شود .

برای اطلاعات بیشتر در مورد API به مقاله Private Aggregation مراجعه کنید.

تجمیع سیگنال های حراج

شما می توانید سیگنال های موجود در Worklet ها را با استفاده از Private Aggregation به سرور خود تجمیع کنید. برای تجمیع سیگنال، می‌توانید از متد privateAggregation.contributeToHistogram() موجود در Worklet پیشنهاد خرید، کارگروه امتیازدهی فروشنده و گزارش خریدار/فروشنده استفاده کنید.

در این مثال، پیشنهاد برنده در سطل مالک گروه ذینفع جمع می‌شود:

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
}

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

تجمیع سیگنال های حراج با داده های رویداد

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

برای جمع‌آوری سیگنال‌های حراج بر اساس رویدادها، می‌توانید از privateAggregation.contributeToHistogramOnEvent(eventType, contribution) استفاده کنید که رشته‌ای را می‌گیرد که نوع رویداد و سهمی را که باید هنگام راه‌اندازی آن رویداد گزارش شود را مشخص می‌کند. می‌توانید روش را با یک نوع رویداد سفارشی فراخوانی کنید، سپس، window.fence.reportEvent(eventType) را از فریم آگهی فراخوانی کنید تا گزارش ارسال شود.

فرض کنید می خواهید اندازه گیری کنید که یک تبلیغ برای یک کمپین چند کلیک دریافت کرده است.

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

در تابع تولید پیشنهاد، می توانید یک سطل را به عنوان ترکیبی از شناسه کمپین و رویداد کلیک تعریف کنید، سپس هر بار که رویداد راه اندازی می شود، مقدار آن سطل را 1 افزایش دهید.

// Ad frame
window.fence.reportEvent('click');

سپس، در زمان دیگری، از قاب تبلیغات، می‌توانید با فراخوانی reportEvent(eventType) ارسال گزارش را فعال کنید:

درباره راه‌اندازی مشارکت‌های جمع خصوصی از یک قاب از توضیح دهنده بیشتر بیاموزید.

گزارش نتایج و عملکرد مزایده

همچنین می‌توانید نتایج حراج را هنگامی که توسط یک رویداد برد یا باخت حراج راه‌اندازی می‌شود، با contributeToHistogramOnEvent(eventType, contribution) جمع‌آوری کنید، هنگامی که یک رویداد رزرو شده را از نوع کلمات کلیدی ( reserved.win, reserved.loss ، و reserved.always ) عبور می‌دهید.

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

هنگامی که مقداری پایه ارائه می شود، مانند مبلغ پیشنهادی برنده، می توانید تعیین کنید که چقدر از آن مقدار اضافه یا کم کنید، سپس مقدار نهایی را گزارش کنید. به عنوان مثال، اگر پیشنهاد برنده 5 دلاری به عنوان ارزش پایه ارائه شده باشد، می توانید پیشنهاد 2 دلاری خود را کم کنید تا ارزش واقعی 3 دلار از میزان ضرری که در حراج خود داشته اید را محاسبه کنید.

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

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

برای اینکه بدانید چقدر در حراج ضرر کرده اید، می توانید قیمت پیشنهادی خود را از قیمت پیشنهادی برنده کم کنید:

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

هنگامی که گزارش ارسال می شود، مقدار واقعی گزارش شده، baseValue مقیاس شده است که توسط مقدار offset جابه جا شده است. برای کسب اطلاعات بیشتر به توضیح دهنده مراجعه کنید.

گزارش عملکرد

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

برای کسب اطلاعات بیشتر به توضیح دهنده مراجعه کنید.

ذخیره سیگنال های حراج در ذخیره سازی مشترک

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

همچنین می‌توانید از مجموعه‌های مناقصه، امتیازدهی و گزارش‌دهی Protected Audience API در فضای ذخیره‌سازی مشترک بنویسید. در زمان بعدی، می‌توانید آن مقادیر را در فضای ذخیره‌سازی مشترک با استفاده از Private Aggregation به سرور خود گزارش دهید. همچنین می توانید از مقادیر ذخیره شده برای عملیات انتخاب URL استفاده کنید.

از یک Worklet Protected Audience API، می‌توانید هر کلید و مقداری را در فضای ذخیره‌سازی مشترک بنویسید:

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

بعداً، می‌توانید یک Worklet ذخیره‌سازی مشترک را برای خواندن و ارسال آن مقدار با Private Aggregation بارگیری کنید:

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

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

بعدش چی؟

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

در مورد API بحث کنید

مانند سایر APIهای Privacy Sandbox، این API مستند شده و به صورت عمومی مورد بحث قرار گرفته است.

با API آزمایش کنید

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