نمای کلی API Aggregation خصوصی

گزارش‌های داده‌ای تجمیعی را با استفاده از داده‌های Protected Audience و داده‌های بین سایتی از Shared Storage ایجاد کنید.

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

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

API تجمیع خصوصی چیست؟

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

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

برای مثال، اگر قبلاً داده‌های جمعیت‌شناختی و جغرافیایی را در Shared Storage ثبت کرده‌اید، می‌توانید از API تجمیع خصوصی برای ساخت یک هیستوگرام استفاده کنید که تقریباً به شما می‌گوید چند کاربر در شهر نیویورک محتوای شما را در سایت‌های مختلف دیده‌اند. برای تجمیع این اندازه‌گیری، می‌توانید بُعد جغرافیایی را در کلید تجمیع کدگذاری کنید و کاربران را در مقدار قابل تجمیع بشمارید.

مفاهیم کلیدی

وقتی API تجمیع خصوصی را با یک کلید تجمیع و یک مقدار تجمیع‌پذیر فراخوانی می‌کنید، مرورگر یک گزارش تجمیع‌پذیر ایجاد می‌کند.

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

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

تفاوت‌ها با گزارش انتساب

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

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

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

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

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

از نسخه نمایشی استفاده کنید

نسخه آزمایشی API تجمیع خصوصی برای ذخیره‌سازی مشترک در goo.gle/shared-storage-demo قابل دسترسی است و کد آن در GitHub موجود است. این نسخه آزمایشی عملیات سمت کلاینت را پیاده‌سازی می‌کند و یک گزارش تجمیع‌پذیر تولید می‌کند که به سرور شما ارسال می‌شود.

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

موارد استفاده

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

با فضای ذخیره‌سازی مشترک

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

اندازه‌گیری منحصر به فرد دسترسی

شاید بخواهید تعداد کاربران منحصر به فرد محتوای خود را اندازه‌گیری کنید. API تجمیع خصوصی می‌تواند پاسخی مانند «تقریباً ۳۱۷ کاربر منحصر به فرد، شناسه محتوای ۸۶۱ را دیده‌اند» ارائه دهد.

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

سنجش جمعیت‌شناختی

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

تجمیع خصوصی می‌تواند پاسخی مانند «تقریباً ۳۱۷ کاربر منحصر به فرد بین ۱۸ تا ۴۵ سال سن دارند و اهل آلمان هستند» ارائه دهد. از فضای ذخیره‌سازی مشترک برای دسترسی به داده‌های جمعیت‌شناختی از یک زمینه شخص ثالث استفاده کنید. در برهه‌ای از زمان، می‌توانید با کدگذاری ابعاد گروه سنی و کشور در کلید تجمیع، گزارشی با تجمیع خصوصی ایجاد کنید.

اندازه‌گیری فرکانس K+

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

تجمیع خصوصی می‌تواند پاسخی مانند «تقریباً ۸۹ کاربر، شناسه محتوای ۵۸۱ را حداقل ۳ بار دیده‌اند» ارائه دهد. یک شمارنده می‌تواند در فضای ذخیره‌سازی مشترک از سایت‌های مختلف افزایش یابد و در یک برگه کاری خوانده شود. هنگامی که تعداد به K رسید، می‌توان با استفاده از تجمیع خصوصی، گزارشی ارسال کرد.

انتساب چند لمسی

انتساب بازاریابی روشی است که توسط تبلیغ‌کنندگان برای تعیین سهم تاکتیک‌های بازاریابی و تعاملات تبلیغاتی بعدی در فروش یا تبدیل‌ها استفاده می‌شود.

با API مخاطب محافظت‌شده

API مخاطب محافظت‌شده (Protected Audience API) امکان هدف‌گیری مجدد و موارد استفاده سفارشی مخاطبان را فراهم می‌کند و تجمیع خصوصی (Private Aggregation) به شما امکان می‌دهد رویدادها را از دفترچه‌های کار خریدار و فروشنده گزارش دهید. این API می‌تواند برای کارهایی مانند اندازه‌گیری توزیع پیشنهادهای حراج استفاده شود.

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

توابع موجود

توابع زیر در شیء privateAggregation موجود در کتابچه‌های Shared Storage و Protected Audience API موجود هستند.

تابع ()countToHistogram

می‌توانید privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }) را فراخوانی کنید، که در آن کلید تجمیع bucket و مقدار قابل تجمیع value است. برای پارامتر bucket ، یک BigInt لازم است. برای پارامتر value ، یک عدد صحیح Number لازم است.

در اینجا مثالی از نحوه فراخوانی آن در Shared Storage برای اندازه‌گیری دسترسی آورده شده است:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', {
  data: { contentId: '1234' }
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await sharedStorage.get(key) === 'true';

    // Don't send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId),
      value: 1 * SCALE_FACTOR
    });

    // Set the flag in Shared Storage
    await sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

مثال کد قبلی، هر زمان که محتوای iframe بین سایتی بارگذاری شود، Private Aggregation را فراخوانی می‌کند. کد iframe، worklet را بارگذاری می‌کند و worklet، API Private Aggregation را با شناسه محتوا که به یک کلید تجمیع (bucket) تبدیل شده است، فراخوانی می‌کند.

تابع ()countToHistogramOnEvent به هیستوگرام کمک می‌کند

فقط در Workbookهای Protected Audience API، ما یک مکانیزم مبتنی بر trigger برای ارسال گزارش فقط در صورت وقوع یک رویداد خاص ارائه می‌دهیم. این عملکرد همچنین به Bucket و مقدار اجازه می‌دهد تا به سیگنال‌هایی که هنوز در آن نقطه از حراج در دسترس نیستند، وابسته باشند.

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

برای ارسال گزارش برای رویدادهای حراج، می‌توانید از دو کلمه کلیدی رزرو شده reserved.win ، reserved.loss و reserved.always استفاده کنید. برای ارسال گزارشی که توسط یک رویداد از یک قاب حصارکشی شده ایجاد می‌شود، یک نوع رویداد سفارشی تعریف کنید. برای ایجاد رویداد از یک قاب حصارکشی شده، از متد fence.reportEvent() موجود در Fenced Frames Ads Reporting API استفاده کنید.

مثال زیر وقتی رویداد برنده شدن در مزایده فعال می‌شود، یک گزارش نمایش (impression report) ارسال می‌کند و اگر رویداد click از فریم حصارکشی شده‌ای که تبلیغ را رندر کرده است، فعال شود، یک گزارش کلیک (click report) ارسال می‌کند. از این دو مقدار می‌توان برای محاسبه نرخ کلیک (clickthrough rate) استفاده کرد.

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

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

فعال‌سازی حالت اشکال‌زدایی()

در حالی که کوکی‌های شخص ثالث هنوز در دسترس هستند، ما یک مکانیسم موقت ارائه خواهیم داد که با فعال کردن حالت اشکال‌زدایی، امکان اشکال‌زدایی و آزمایش آسان‌تر را فراهم می‌کند. گزارش اشکال‌زدایی در مقایسه اندازه‌گیری‌های مبتنی بر کوکی با اندازه‌گیری‌های Private Aggregation شما مفید است و همچنین به شما امکان می‌دهد تا به سرعت ادغام API خود را تأیید کنید.

فراخوانی privateAggregation.enableDebugMode() در worklet حالت اشکال‌زدایی را فعال می‌کند که باعث می‌شود گزارش‌های تجمیع‌پذیر شامل محتوای رمزگذاری نشده (متن واضح) باشند. سپس می‌توانید این محتواها را با ابزار تست محلی Aggregation Service پردازش کنید.

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

همچنین می‌توانید با فراخوانی privateAggregation.enableDebugMode({ <debugKey: debugKey> }) کلید اشکال‌زدایی را تنظیم کنید، که در آن می‌توان از یک BigInt به عنوان کلید اشکال‌زدایی استفاده کرد. کلید اشکال‌زدایی می‌تواند برای مرتبط کردن داده‌ها از یک اندازه‌گیری مبتنی بر کوکی و داده‌های حاصل از اندازه‌گیری Private Aggregation استفاده شود.

این‌ها را می‌توان فقط یک بار در هر context فراخوانی کرد. هرگونه فراخوانی بعدی منجر به ایجاد یک استثنا خواهد شد.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

گزارش تأیید

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

تنظیم شناسه زمینه به اطمینان از صحت داده‌ها هنگام مشارکت در نتایج نهایی کمک می‌کند. این امر از طریق موارد زیر محقق می‌شود:

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

فضای ذخیره‌سازی مشترک

هنگام استفاده از Shared Storage برای اجرای عملیاتی که می‌تواند یک گزارش تجمیعی ارسال کند، می‌توانید یک شناسه غیرقابل پیش‌بینی خارج از Worklet تنظیم کنید.

این شناسه در گزارش ایجاد شده از worklet تعبیه شده است. می‌توانید آن را هنگام فراخوانی متدهای run() یا selectURL() Shared Storage، درون شیء options زیر کلید privateAggregationConfig مشخص کنید.

برای مثال:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

پس از تنظیم این شناسه، می‌توانید از آن برای تأیید ارسال گزارش از عملیات Shared Storage خود استفاده کنید. برای جلوگیری از نشت اطلاعات، صرف نظر از تعداد فراخوانی‌های contributeToHistogram() ، دقیقاً یک گزارش به ازای هر عملیات Shared Storage ارسال می‌شود (حتی اگر هیچ مشارکتی انجام نشود).

API تجمیع خصوصی، گزارش‌های تجمیعی را با تأخیر تصادفی تا یک ساعت ارسال می‌کند. با این حال، تنظیم شناسه زمینه برای تأیید گزارش، این تأخیر را کاهش می‌دهد. در این حالت، یک تأخیر ثابت و کوچک‌تر ۵ ثانیه‌ای از شروع عملیات ذخیره‌سازی مشترک وجود دارد.

یک نمونه گردش کار (همانطور که در نمودار بالا نشان داده شده است):

1. عملیات Shared Storage با پیکربندی Private Aggregation که یک شناسه زمینه (context ID) را مشخص می‌کند، اجرا می‌شود و یک گزارش قابل تجمیع تولید می‌شود.
2. شناسه زمینه در گزارش تجمیعی تولید شده که به سرور شما ارسال می‌شود، تعبیه شده است.
3. سرور شما گزارش‌های قابل جمع‌آوری تولید شده را جمع‌آوری می‌کند.
4. فرآیندهای روی سرور شما، شناسه زمینه (context ID) در هر گزارش قابل تجمیع را با شناسه‌های زمینه ذخیره شده شما مقایسه می‌کنند تا اعتبار آن را قبل از دسته‌بندی گزارش‌ها و ارسال آنها به سرویس تجمیع شما تأیید کنند.

تأیید شناسه زمینه

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

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

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

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

• گیت‌هاب : توضیحات را بخوانید، سوال بپرسید و در بحث شرکت کنید .