প্রাইভেট অ্যাগ্রিগেশন API ওভারভিউ

শেয়ার্ড স্টোরেজ থেকে সুরক্ষিত দর্শক এবং ক্রস-সাইট ডেটা ব্যবহার করে সমষ্টিগত ডেটা রিপোর্ট তৈরি করুন।

ওয়েব নির্ভর করে এমন গুরুত্বপূর্ণ বৈশিষ্ট্যগুলি প্রদান করতে, গোপনীয়তা-সংরক্ষণ পদ্ধতিতে ক্রস-সাইট ডেটা একত্রিত এবং প্রতিবেদন করার জন্য ব্যক্তিগত একত্রিতকরণ API তৈরি করা হয়েছে।

বাস্তবায়নের অবস্থা

提案 状态
通过对 Shared Storage 的报告进行验证，防止 Private Aggregation API 报告无效
说明		 在 Chrome 中提供
私有汇总调试模式的可用性取决于 3PC 资格条件
GitHub 问题		 适用于 Chrome M119
缩短报告延迟时间
说明		 适用于 Chrome M119
共享存储空间的 Private Aggregation 贡献超时
说明		 适用于 M119
支持 Google Cloud 专用汇总 API 和汇总服务
解说		 适用于 Chrome M121
可汇总报告载荷的填充
说明		 适用于 Chrome M119
私密汇总调试模式适用于 auctionReportBuyers 报告
说明		 适用于 Chrome M123
过滤 ID 支持
说明		 适用于 Chrome M128
客户端贡献合并
说明		 适用于 Chrome M129
每个情境的贡献限制
说明		 预计 2025 年第 1 季度
命名预算
说明		 预计 2025 年第 1 季度
汇总错误报告
说明		 预计 2025 年第 1 季度

প্রাইভেট অ্যাগ্রিগেশন এপিআই কি?

প্রাইভেট অ্যাগ্রিগেশন এপিআই ডেভেলপারদের প্রোটেক্টেড অডিয়েন্স এপিআই থেকে ডেটা এবং শেয়ার্ড স্টোরেজ থেকে ক্রস-সাইট ডেটা সহ সমষ্টিগত ডেটা রিপোর্ট তৈরি করতে দেয়।

এই API এর প্রধান ফাংশন contributeToHistogram() নামে পরিচিত। হিস্টোগ্রাম অপারেশন আপনাকে আপনার সংজ্ঞায়িত প্রতিটি বালতিতে (এপিআই-এ একত্রীকরণ কী হিসাবে পরিচিত) ব্যবহারকারীদের জুড়ে ডেটা একত্রিত করতে দেয়। আপনার হিস্টোগ্রাম কল মান সংগ্রহ করে এবং একটি সংক্ষিপ্ত প্রতিবেদনের আকারে একটি গোলমাল সমষ্টিগত ফলাফল প্রদান করে। উদাহরণস্বরূপ, প্রতিবেদনটি প্রতিটি ব্যবহারকারী আপনার সামগ্রী দেখেছে এমন সাইটের সংখ্যা দেখাতে পারে বা আপনার তৃতীয় পক্ষের স্ক্রিপ্টে একটি বাগ দেখতে পারে৷ এই অপারেশন অন্য API এর ওয়ার্কলেট মধ্যে সঞ্চালিত হয়.

উদাহরণস্বরূপ, যদি আপনি পূর্বে ভাগ করা সঞ্চয়স্থানে জনসংখ্যাগত এবং ভৌগলিক ডেটা রেকর্ড করে থাকেন তবে আপনি একটি হিস্টোগ্রাম তৈরি করতে ব্যক্তিগত সমষ্টি API ব্যবহার করতে পারেন যা আপনাকে জানায় যে নিউ ইয়র্ক সিটির কতজন ব্যবহারকারী আপনার সামগ্রী ক্রস-সাইট দেখেছেন৷ এই পরিমাপের জন্য একত্রিত করতে, আপনি একত্রীকরণ কীতে ভূগোল মাত্রা এনকোড করতে পারেন এবং সমষ্টিগত মানের মধ্যে ব্যবহারকারীদের গণনা করতে পারেন।

মূল ধারণা

আপনি যখন প্রাইভেট অ্যাগ্রিগেশন এপিআইকে একটি অ্যাগ্রিগেশন কী এবং অ্যাগ্রিগেটেবল ভ্যালু দিয়ে কল করেন, তখন ব্রাউজার একটি অ্যাগ্রিগেটেবল রিপোর্ট তৈরি করে।

সমষ্টিগত প্রতিবেদন সংগ্রহ এবং ব্যাচিংয়ের জন্য আপনার সার্ভারে পাঠানো হয়। ব্যাচ করা রিপোর্টগুলি পরে অ্যাগ্রিগেশন সার্ভিস দ্বারা প্রক্রিয়া করা হয় এবং একটি সারাংশ রিপোর্ট তৈরি করা হয়।

প্রাইভেট অ্যাগ্রিগেশন API এর সাথে জড়িত মূল ধারণাগুলি সম্পর্কে আরও জানতে ব্যক্তিগত সমষ্টি API মৌলিক নথি দেখুন।

অ্যাট্রিবিউশন রিপোর্টিং থেকে পার্থক্য

প্রাইভেট অ্যাগ্রিগেশন এপিআই অ্যাট্রিবিউশন রিপোর্টিং এপিআই- এর সাথে অনেক মিল শেয়ার করে। অ্যাট্রিবিউশন রিপোর্টিং হল একটি স্বতন্ত্র API যা রূপান্তরগুলি পরিমাপ করার জন্য ডিজাইন করা হয়েছে, যেখানে ব্যক্তিগত একত্রীকরণটি প্রোটেক্টেড অডিয়েন্স API এবং শেয়ার্ড স্টোরেজের মতো APIগুলির সাথে একত্রে ক্রস-সাইট পরিমাপের জন্য তৈরি করা হয়েছে৷ উভয় APIই সমষ্টিগত প্রতিবেদন তৈরি করে যা সংক্ষিপ্তসার প্রতিবেদন তৈরি করতে অ্যাগ্রিগেশন সার্ভিস ব্যাক-এন্ড ব্যবহার করে।

অ্যাট্রিবিউশন রিপোর্টিং একটি ইম্প্রেশন ইভেন্ট এবং একটি রূপান্তর ইভেন্ট থেকে সংগৃহীত ডেটা সহযোগী করে, যা বিভিন্ন সময়ে ঘটে। ব্যক্তিগত সমষ্টি একটি একক, ক্রস-সাইট ইভেন্ট পরিমাপ করে।

এই API পরীক্ষা করুন

স্থানীয়ভাবে প্রাইভেট অ্যাগ্রিগেশন API পরীক্ষা করতে, chrome://settings/adPrivacy এর অধীনে সমস্ত বিজ্ঞাপন গোপনীয়তা API সক্ষম করুন।

পরীক্ষায় পরীক্ষা সম্পর্কে আরও পড়ুন এবং অংশগ্রহণ করুন ।

ডেমো ব্যবহার করুন

শেয়ার্ড স্টোরেজের জন্য প্রাইভেট অ্যাগ্রিগেশন API-এর ডেমো goo.gle/shared-storage-demo- এ অ্যাক্সেস করা যেতে পারে এবং কোডটি GitHub- এ উপলব্ধ। ডেমো ক্লায়েন্ট-সাইড ক্রিয়াকলাপগুলিকে প্রয়োগ করে এবং একটি সমষ্টিগত প্রতিবেদন তৈরি করে যা আপনার সার্ভারে পাঠানো হয়।

প্রোটেক্টেড অডিয়েন্স এপিআই-এর জন্য প্রাইভেট অ্যাগ্রিগেশন API-এর একটি ডেমো ভবিষ্যতে প্রকাশিত হবে।

কেস ব্যবহার করুন

ব্যক্তিগত সমষ্টি ক্রস-সাইট পরিমাপের জন্য একটি সাধারণ-উদ্দেশ্য API, এবং এটি শেয়ার্ড স্টোরেজ এবং সুরক্ষিত অডিয়েন্স API ওয়ার্কলেটগুলিতে ব্যবহার করার জন্য উপলব্ধ। প্রথম ধাপ হল নির্দিষ্টভাবে সিদ্ধান্ত নেওয়া যে আপনি কোন তথ্য সংগ্রহ করতে চান। এই ডেটা পয়েন্টগুলি আপনার একত্রিতকরণ কীগুলির ভিত্তি।

শেয়ার্ড স্টোরেজ সহ

শেয়ার্ড স্টোরেজ আপনাকে লিকেজ রোধ করতে একটি নিরাপদ পরিবেশে ক্রস-সাইট ডেটা পড়তে এবং লিখতে দেয় এবং প্রাইভেট অ্যাগ্রিগেশন API আপনাকে শেয়ার্ড স্টোরেজে সংরক্ষিত ক্রস-সাইট ডেটা পরিমাপ করতে দেয়।

অনন্য নাগালের পরিমাপ

আপনি কতজন অনন্য ব্যবহারকারী তাদের সামগ্রী দেখেছেন তা পরিমাপ করতে চাইতে পারেন। Private Aggregation API একটি উত্তর প্রদান করতে পারে যেমন "প্রায় 317 জন অনন্য ব্যবহারকারী Content ID 861 দেখেছেন।"

ব্যবহারকারী ইতিমধ্যে বিষয়বস্তু দেখেছেন কিনা তা বোঝাতে আপনি শেয়ার্ড স্টোরেজে একটি পতাকা সেট করতে পারেন। প্রথম সফরে যেখানে পতাকাটির অস্তিত্ব নেই, সেখানে প্রাইভেট অ্যাগ্রিগেশনের জন্য একটি কল করা হয় এবং তারপর পতাকা সেট করা হয়। ক্রস-সাইট ভিজিট সহ ব্যবহারকারীর পরবর্তী ভিজিটগুলিতে, আপনি শেয়ার্ড স্টোরেজ চেক করতে পারেন এবং পতাকা সেট করা থাকলে ব্যক্তিগত সমষ্টিতে একটি প্রতিবেদন জমা দেওয়া এড়িয়ে যেতে পারেন। এই পরিমাপগুলি বাস্তবায়নের পদ্ধতি সম্পর্কে আরও জানতে, আমাদের নাগালের শ্বেতপত্র দেখুন।

জনসংখ্যার পরিমাপ

আপনি বিভিন্ন সাইট জুড়ে আপনার সামগ্রী দেখেছেন এমন ব্যবহারকারীদের জনসংখ্যার পরিমাপ করতে চাইতে পারেন।

ব্যক্তিগত সমষ্টি একটি উত্তর প্রদান করতে পারে, যেমন "প্রায় 317 জন অনন্য ব্যবহারকারী 18-45 বছর বয়সী এবং জার্মানি থেকে এসেছেন।" তৃতীয় পক্ষের প্রসঙ্গ থেকে জনসংখ্যার তথ্য অ্যাক্সেস করতে শেয়ার্ড স্টোরেজ ব্যবহার করুন। পরবর্তী সময়ে, আপনি সমষ্টি কী-তে বয়স গোষ্ঠী এবং দেশের মাত্রা এনকোড করে ব্যক্তিগত সমষ্টির সাথে একটি প্রতিবেদন তৈরি করতে পারেন।

K+ ফ্রিকোয়েন্সি পরিমাপ

K-এর পূর্ব-নির্বাচিত মানের জন্য, একটি নির্দিষ্ট ব্রাউজারে অন্তত K বার কন্টেন্ট বা বিজ্ঞাপন দেখেছেন এমন ব্যবহারকারীর সংখ্যা আপনি পরিমাপ করতে চাইতে পারেন।

ব্যক্তিগত সমষ্টি একটি উত্তর প্রদান করতে পারে যেমন "প্রায় 89 জন ব্যবহারকারী কমপক্ষে 3 বার Content ID 581 দেখেছেন।" বিভিন্ন সাইট থেকে শেয়ার্ড স্টোরেজে একটি কাউন্টার বৃদ্ধি করা যেতে পারে এবং একটি ওয়ার্কলেটের মধ্যে পড়া যেতে পারে। গণনা K-তে পৌঁছে গেলে, ব্যক্তিগত সমষ্টির মাধ্যমে একটি প্রতিবেদন জমা দেওয়া যেতে পারে।

প্রোটেক্টেড অডিয়েন্স এপিআই সহ

প্রোটেক্টেড অডিয়েন্স এপিআই রিটার্গেটিং এবং কাস্টম অডিয়েন্স ইউজ কেস সক্ষম করে এবং প্রাইভেট অ্যাগ্রিগেশন আপনাকে ক্রেতা এবং বিক্রেতার ওয়ার্কলেট থেকে ইভেন্ট রিপোর্ট করতে দেয়। এপিআই নিলাম বিডের বিতরণ পরিমাপের মতো কাজের জন্য ব্যবহার করা যেতে পারে।

একটি সুরক্ষিত শ্রোতা API ওয়ার্কলেট থেকে, আপনি contributeToHistogram() ব্যবহার করে সরাসরি আপনার ডেটা একত্রিত করতে পারেন এবং contributeToHistogramOnEvent() ব্যবহার করে একটি ট্রিগারের ভিত্তিতে আপনার ডেটা রিপোর্ট করতে পারেন, যা সুরক্ষিত দর্শক API-এর জন্য একটি বিশেষ এক্সটেনশন৷

উপলব্ধ ফাংশন

শেয়ার্ড স্টোরেজ এবং প্রোটেক্টেড অডিয়েন্স এপিআই ওয়ার্কলেটে উপলব্ধ privateAggregation অবজেক্টে নিম্নলিখিত ফাংশনগুলি উপলব্ধ।

হিস্টোগ্রামে অবদান করুন()

আপনি কল করতে পারেন privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }) , যেখানে একত্রীকরণ কীটি bucket এবং সমষ্টিগত মানটিকে value হিসাবে। bucket প্যারামিটারের জন্য, একটি BigInt প্রয়োজন। value প্যারামিটারের জন্য, একটি পূর্ণসংখ্যার প্রয়োজন।

নাগালের পরিমাপের জন্য শেয়ার্ড স্টোরেজে এটিকে কীভাবে বলা যেতে পারে তার একটি উদাহরণ এখানে দেওয়া হল:

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';

    // Do not 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 কোড ওয়ার্কলেট লোড করে, এবং ওয়ার্কলেটটি একটি অ্যাগ্রিগেশন কী (বালতি) তে রূপান্তরিত বিষয়বস্তু আইডি সহ প্রাইভেট অ্যাগ্রিগেশন API কল করে।

অবদান করুন হিস্টোগ্রামঅনইভেন্ট()

শুধুমাত্র প্রোটেক্টেড অডিয়েন্স এপিআই ওয়ার্কলেটের মধ্যে, একটি নির্দিষ্ট ঘটনা ঘটলেই শুধুমাত্র রিপোর্ট পাঠানোর জন্য আমরা একটি ট্রিগার-ভিত্তিক প্রক্রিয়া প্রদান করি। এই ফাংশনটি বালতি এবং মানকে সিগন্যালের উপর নির্ভর করার অনুমতি দেয় যা নিলামের সেই সময়ে এখনও উপলব্ধ নয়।

privateAggregation.contributeToHistogramOnEvent(eventType, contribution) পদ্ধতিটি একটি eventType নেয় যা ট্রিগারিং ইভেন্ট এবং ইভেন্টটি ট্রিগার করার সময় জমা দেওয়ার জন্য contribution নির্দিষ্ট করে। ট্রিগারিং ইভেন্টটি নিলাম শেষ হওয়ার পরেই নিলাম থেকে আসতে পারে, যেমন একটি নিলামে জয় বা হারের ঘটনা, অথবা এটি বিজ্ঞাপনটি রেন্ডার করা একটি বেড়াযুক্ত ফ্রেম থেকে আসতে পারে। নিলাম ইভেন্টগুলির জন্য একটি প্রতিবেদন পাঠাতে, আপনি দুটি সংরক্ষিত কীওয়ার্ড ব্যবহার করতে পারেন, reserved.win , reserved.loss , এবং reserved.always । একটি বেড়াযুক্ত ফ্রেম থেকে একটি ইভেন্ট দ্বারা ট্রিগার করা একটি প্রতিবেদন জমা দিতে, একটি কাস্টম ইভেন্ট প্রকার সংজ্ঞায়িত করুন৷ একটি বেড়াযুক্ত ফ্রেম থেকে ইভেন্টটি ট্রিগার করতে, ফেন্সড ফ্রেম বিজ্ঞাপন রিপোর্টিং API থেকে উপলব্ধ fence.reportEvent() পদ্ধতিটি ব্যবহার করুন৷

নিলামে জয়ের ইভেন্টটি ট্রিগার হলে নিচের উদাহরণটি একটি ইম্প্রেশন রিপোর্ট পাঠায় এবং বিজ্ঞাপনটি রেন্ডার করা বেড়াযুক্ত ফ্রেম থেকে একটি click ইভেন্ট ট্রিগার হলে একটি ক্লিক রিপোর্ট পাঠায়। এই দুটি মান ক্লিকথ্রু হার গণনা করতে ব্যবহার করা যেতে পারে।

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
  });

আরও জানতে এক্সটেন্ডেড প্রাইভেট অ্যাগ্রিগেশন রিপোর্টিং ব্যাখ্যাকারী দেখুন।

সক্ষম ডিবাগমোড()

যদিও তৃতীয় পক্ষের কুকিগুলি এখনও উপলব্ধ রয়েছে, আমরা একটি অস্থায়ী পদ্ধতি প্রদান করব যা ডিবাগ মোড সক্ষম করে সহজে ডিবাগিং এবং পরীক্ষা করার অনুমতি দেয়৷ একটি ডিবাগ রিপোর্ট আপনার কুকি-ভিত্তিক পরিমাপগুলিকে আপনার ব্যক্তিগত সমষ্টির পরিমাপের সাথে তুলনা করার জন্য দরকারী, এবং এছাড়াও আপনাকে আপনার API একীকরণকে দ্রুত যাচাই করার অনুমতি দেয়৷

ওয়ার্কলেটে privateAggregation.enableDebugMode() কল করা ডিবাগ মোডকে সক্রিয় করে যার ফলে এনক্রিপ্ট না করা (ক্লিয়ারটেক্সট) পেলোড অন্তর্ভুক্ত করার জন্য একত্রিত প্রতিবেদন তৈরি হয়। তারপর আপনি এই পেলোডগুলিকে অ্যাগ্রিগেশন সার্ভিস স্থানীয় টেস্টিং টুল দিয়ে প্রক্রিয়া করতে পারেন৷

ডিবাগ মোড শুধুমাত্র সেই কলারদের জন্য উপলব্ধ যারা তৃতীয় পক্ষের কুকিজ অ্যাক্সেস করতে পারবেন। কলারের যদি তৃতীয় পক্ষের কুকিগুলিতে অ্যাক্সেস না থাকে, enableDebugMode() নিঃশব্দে ব্যর্থ হবে৷ এর মানে হল যে যখন তৃতীয় পক্ষের কুকিগুলিকে অবমূল্যায়ন করা হয় তখন ডিবাগ মোড আর উপলব্ধ থাকবে না৷

এছাড়াও আপনি privateAggregation.enableDebugMode({ <debugKey: debugKey> }) কল করে ডিবাগ কী সেট করতে পারেন যেখানে একটি BigInt একটি ডিবাগ কী হিসাবে ব্যবহার করা যেতে পারে। ডিবাগ কীটি কুকি-ভিত্তিক পরিমাপ এবং ব্যক্তিগত সমষ্টি পরিমাপ থেকে ডেটা সংযুক্ত করতে ব্যবহার করা যেতে পারে।

এগুলি কেবলমাত্র প্রতি প্রসঙ্গে একবার বলা যেতে পারে। পরবর্তী যে কোনো কল একটি ব্যতিক্রম নিক্ষেপ করবে। 

// Enables debug mode
privateAggregation.enableDebugMode();

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

রিপোর্ট যাচাইকরণ

শেয়ার্ড স্টোরেজের জন্য, শেয়ার্ড স্টোরেজ অপারেশন কলে একটি প্রসঙ্গ আইডি যোগ করে আপনি প্রাপ্ত সমষ্টিগত প্রতিবেদনগুলি বৈধ কিনা তা যাচাই করতে পারেন। আইডিটি প্রেরিত প্রতিবেদনের সাথে সংযুক্ত করা হবে এবং পরবর্তী সময়ে, আপনি সেই আইডিটি ব্যবহার করে যাচাই করতে পারেন যে প্রতিবেদনটি আপনার শেয়ার্ড স্টোরেজ অপারেশন থেকে পাঠানো হয়েছে।

আরও জানতে, রিপোর্ট যাচাইকরণ ব্যাখ্যাকারী দেখুন।

জড়িত এবং মতামত শেয়ার করুন

প্রাইভেট অ্যাগ্রিগেশন API সক্রিয় আলোচনার অধীনে রয়েছে এবং ভবিষ্যতে পরিবর্তন হতে পারে। আপনি যদি এই APIটি চেষ্টা করেন এবং প্রতিক্রিয়া জানান, আমরা এটি শুনতে চাই।