گزارش حراج 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‌های گزارش‌دهی مختلف در دسترس برای گزارش داده‌هایی مانند سیگنال‌های حراج، داده‌های سطح رویداد و داده‌های تبدیل دسترسی خواهند داشت.

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

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

سیگنال ها

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

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

داده ها و نتایج حراج 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‌های گزارش‌دهی مختلف در دسترس برای گزارش داده‌هایی مانند سیگنال‌های حراج، داده‌های سطح رویداد و داده‌های تبدیل دسترسی خواهند داشت.

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

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

سیگنال ها

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

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

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

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

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

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']
})

برای کسب اطلاعات بیشتر به بخش گزارش انتساب API Reporting API API مراجعه کنید.

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

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

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

گردش کار:

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

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

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

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

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

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

برای اطلاعات بیشتر در مورد API به مقاله جمع آوری خصوصی مراجعه کنید.

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

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

در این مثال ، پیشنهاد برنده در سطل صاحب گروه علاقه جمع می شود:

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 . Always) انجام دهید.

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

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

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

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

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

بعداً می توانید یک کار ذخیره سازی مشترک را برای خواندن و ارسال آن با جمع آوری خصوصی بارگیری کنید:

// 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 مخاطبان محافظت شده شرکت کنید .