گزارش اسناد برای نمای کلی تلفن همراه

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

به روز رسانی های اخیر

• لیست تغییرات آتی و مشکلات شناخته شده را به روز کرد

• پیکربندی انعطاف پذیر در سطح رویداد را به عنوان پلی برای پیکربندی کامل در سطح رویداد انعطاف پذیر معرفی کرد.

• از سپتامبر 2023، registerWebSource ، registerWebTrigger ، registerAppSource و registerAppTrigger باید از رشته‌هایی برای فیلدهایی که انتظار یک مقدار عددی دارند (مانند priority ، source_event_id ، debug_key ، trigger_data ، deduplication_key ، و غیره) استفاده کنند.

• در سه ماهه چهارم 2023، پشتیبانی Google Cloud در Android Attribution Reporting API برای تولید گزارش‌های خلاصه با استفاده از سرویس تجمیع در Google Cloud اضافه می‌شود که زمان‌بندی مشخص‌تری در اینجا منعکس شده است. برای اطلاعات بیشتر در مورد راه‌اندازی سرویس جمع‌آوری با Google Cloud، راهنمای استقرار را ببینید.

• محدودیت‌های نرخ حفظ حریم خصوصی جدید برای تعداد مقصدهای منحصر به فرد.

• عملکرد به روز شده برای فیلترهای ماشه پنجره بازبینی در سه ماهه اول 2024 ارائه می شود، برای اطلاعات بیشتر به یادداشت مراجعه کنید.

نمای کلی

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

این API دارای مکانیسم‌های ساختاری زیر است که چارچوبی را برای بهبود حریم خصوصی ارائه می‌دهد که در بخش‌های بعدی این صفحه با جزئیات بیشتر توضیح داده می‌شود:

• تعداد بیت های موجود برای گزارش های سطح رویداد را محدود می کند

• داده‌های تبدیل با وفاداری بالاتر را فقط در گزارش‌های انبوهی فعال می‌کند

• محدودیت‌های نرخ را برای محرک‌های موجود (تبدیل‌ها) و تعداد فناوری‌های تبلیغاتی که می‌توانند با یک منبع انتساب مرتبط شوند معرفی می‌کند.

• شامل تکنیک های مختلف افزایش نویز است

مکانیسم های قبلی توانایی پیوند دادن هویت کاربر را بین دو برنامه یا دامنه متفاوت محدود می کند.

Attribution Reporting API موارد استفاده زیر را پشتیبانی می کند:

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

در سطح بالا، API گزارش انتساب به شرح زیر عمل می کند، که بخش های بعدی این سند با جزئیات بیشتر توضیح می دهد:

1. فناوری تبلیغات یک فرآیند ثبت‌نام را برای استفاده از Attribution Reporting API تکمیل می‌کند .
2. فناوری تبلیغات منابع انتساب -کلیک‌ها یا بازدیدهای تبلیغاتی- را با API گزارش Attribution ثبت می‌کند .
3. فناوری تبلیغات، محرک‌ها - تبدیل‌های کاربر در برنامه یا وب‌سایت تبلیغ‌کننده - را با Attribution Reporting API ثبت می‌کند .
4. Attribution Reporting API محرک‌ها را با منابع انتساب منطبق می‌کند - یک انتساب تبدیل - و یک یا چند محرک خارج از دستگاه از طریق گزارش‌های سطح رویداد و جمع‌آوری‌شده به فناوری‌های تبلیغاتی ارسال می‌شوند.

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

به APIهای Attribution Reporting دسترسی پیدا کنید

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

ثبت منبع انتساب (کلیک کنید یا مشاهده کنید)

Attribution Reporting API به کلیک ها و بازدیدهای تبلیغاتی به عنوان منابع انتساب اشاره می کند. برای ثبت کلیک یا مشاهده آگهی، با registerSource() تماس بگیرید. این API پارامترهای زیر را انتظار دارد:

• URI منبع انتساب: پلتفرم درخواستی را به این URI صادر می کند تا متادیتا مرتبط با منبع انتساب را واکشی کند.
• رویداد ورودی: یا یک شی InputEvent (برای یک رویداد کلیک) یا null (برای یک رویداد مشاهده).

هنگامی که API درخواستی به URI منبع منبع می‌دهد، فناوری تبلیغات باید با فراداده منبع انتساب در یک عنوان HTTP جدید Attribution-Reporting-Register-Source با فیلدهای زیر پاسخ دهد:

• شناسه رویداد منبع : این مقدار داده‌های سطح رویداد مرتبط با این منبع انتساب (کلیک یا مشاهده آگهی) را نشان می‌دهد. باید یک عدد صحیح بدون علامت 64 بیتی باشد که به صورت رشته فرمت شده است.
• مقصد : مبدایی که eTLD+1 یا نام بسته برنامه آن در آن رویداد ماشه رخ می دهد.
• انقضا (اختیاری) : انقضا، در چند ثانیه، برای زمانی که منبع باید از دستگاه حذف شود. پیش‌فرض 30 روز با حداقل مقدار 1 روز و حداکثر مقدار 30 روز است. این به نزدیکترین روز گرد می شود. می تواند به عنوان یک عدد صحیح بدون علامت 64 بیتی یا رشته ای قالب بندی شود.
• پنجره گزارش رویداد (اختیاری) : مدت زمان بر حسب ثانیه پس از ثبت منبع که طی آن ممکن است گزارش رویداد برای این منبع ایجاد شود. اگر پنجره گزارش رویداد گذشته باشد، اما انقضا هنوز به پایان نرسیده است، باز هم می‌توان یک راه‌انداز را با یک منبع مطابقت داد، اما گزارش رویداد برای آن راه‌انداز ارسال نمی‌شود. نمی تواند بزرگتر از Expiry باشد. می تواند به عنوان یک عدد صحیح بدون علامت 64 بیتی یا رشته ای قالب بندی شود.
• پنجره گزارش انبوه (اختیاری) : مدت زمان بر حسب ثانیه پس از ثبت منبع که طی آن ممکن است گزارش های انبوهی برای این منبع ایجاد شود. نمی تواند بزرگتر از Expiry باشد. می تواند به عنوان یک عدد صحیح بدون علامت 64 بیتی یا رشته ای قالب بندی شود.
• اولویت منبع (اختیاری) : برای انتخاب منبع انتساب که یک راه‌انداز معین باید با کدام منبع انتساب مرتبط باشد، استفاده می‌شود، در صورتی که چندین منبع انتساب می‌تواند با محرک مرتبط باشد. باید یک عدد صحیح امضا شده 64 بیتی باشد که به صورت رشته فرمت شده است.
  
  هنگامی که یک ماشه دریافت می شود، API منبع انتساب منطبق را با بالاترین مقدار اولویت منبع پیدا می کند و یک گزارش ایجاد می کند. هر پلتفرم فناوری تبلیغاتی می تواند استراتژی اولویت بندی خود را تعریف کند. برای جزئیات بیشتر در مورد چگونگی تأثیر اولویت بر انتساب، به بخش مثال اولویت بندی مراجعه کنید.
  
  مقادیر بالاتر نشان دهنده اولویت های بالاتر است.
• نصب و پنجره های انتساب پس از نصب (اختیاری): برای تعیین انتساب رویدادهای پس از نصب استفاده می شود که در ادامه در این صفحه توضیح داده شده است.
• فیلتر داده ها (اختیاری): برای فیلتر کردن انتخابی برخی از محرک ها و نادیده گرفتن آنها استفاده می شود. برای جزئیات بیشتر، بخش فیلترهای ماشه را در این صفحه ببینید.
• کلیدهای تجمیع (اختیاری): تقسیم بندی را مشخص کنید تا برای گزارش های جمع آوری استفاده شود.

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

راهنمای توسعه دهنده شامل نمونه هایی است که نحوه پذیرش ثبت منبع را نشان می دهد.

مراحل زیر یک نمونه گردش کار را نشان می دهد:

1. SDK فناوری تبلیغات، API را فراخوانی می‌کند تا ثبت منبع انتساب را آغاز کند، و یک URI برای API برای فراخوانی مشخص می‌کند:

   registerSource(
       Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
       myClickEvent);
   

2. API از https://adtech.example/attribution_source? AD_TECH_PROVIDED_METADATA ، با استفاده از یکی از سرصفحه‌های زیر:

   <!-- For click events -->
   Attribution-Reporting-Source-Info: navigation
   
   <!-- For view events -->
   Attribution-Reporting-Source-Info: event
   

3. سرور HTTPS این فناوری تبلیغاتی با سرصفحه هایی حاوی موارد زیر پاسخ می دهد:

   Attribution-Reporting-Register-Source: {
       "destination": "android-app://com.advertiser.example",
       "source_event_id": "234",
       "expiry": "60000",
       "priority": "5"
   }
   Attribution-Reporting-Redirect:
   https://adtechpartner1.example?their_ad_click_id=567
   Attribution-Reporting-Redirect:
   https://adtechpartner2.example?their_ad_click_id=890
   

4. API برای هر URL مشخص شده در Attribution-Reporting-Redirect درخواست می کند. در این مثال، دو URL شریک فناوری تبلیغاتی مشخص شده‌اند، بنابراین API یک درخواست به https://adtechpartner1.example?their_ad_click_id=567 و یک درخواست دیگر به https://adtechpartner2.example?their_ad_click_id=890 می‌دهد.

5. سرور HTTPS این فناوری تبلیغاتی با سرصفحه هایی حاوی موارد زیر پاسخ می دهد:

   Attribution-Reporting-Register-Source: {
       "destination": "android-app://com.advertiser.example",
       "source_event_id": "789",
       "expiry": "120000",
       "priority": "2"
   }
   

   توجه: پاسخ‌های متخصصان تبلیغات می‌توانند ابرداده‌های مختلفی را در سرصفحه Attribution-Reporting-Register-Source مشخص کنند.

سه منبع انتساب ناوبری (کلیک کنید) بر اساس درخواست های نشان داده شده در مراحل قبلی ثبت می شود.

یک منبع انتساب از WebView ثبت کنید

WebView از مورد استفاده پشتیبانی می کند که یک برنامه در حال ارائه یک تبلیغ در یک وب سایت است. این توسط WebView که مستقیماً registerSource() به عنوان یک درخواست پس‌زمینه فراخوانی می‌کند، مدیریت می‌شود. این تماس منبع انتساب را به جای مبدا سطح بالا به برنامه مرتبط می کند. ثبت منابع از محتوای وب جاسازی شده در یک زمینه مرورگر نیز پشتیبانی می شود. هم تماس گیرندگان API و هم برنامه ها برای انجام این کار باید تنظیمات را انجام دهند. برای دستورالعمل‌های مربوط به تماس‌گیرندگان API و منبع Attribution و برای دستورالعمل‌های برنامه‌ها، ثبت منبع و راه‌انداز انتساب از WebView را ببینید.

از آنجایی که فناوری‌های تبلیغاتی از کدهای مشترک در وب و WebView استفاده می‌کنند، WebView از تغییر مسیرهای HTTP 302 پیروی می‌کند و ثبت‌های معتبر را به پلتفرم منتقل می‌کند. ما قصد نداریم از سرصفحه Attribution-Reporting-Redirect برای این سناریو پشتیبانی کنیم، اما اگر مورد استفاده شما تأثیرگذار است، تماس بگیرید .

توجه: برای اجازه دادن به WebViews برای استفاده از Attribution Reporting API، برنامه جاسازی باید با مجوزهای صحیح پیکربندی شود.

ثبت یک ماشه (تبدیل)

پلتفرم‌های فناوری تبلیغات می‌توانند با استفاده از روش registerTrigger() تریگرها را ثبت کنند - تبدیل‌هایی مانند نصب یا رویدادهای پس از نصب.

متد registerTrigger() انتظار پارامتر Trigger URI را دارد. API درخواستی برای این URI برای واکشی ابرداده مرتبط با راه‌انداز صادر می‌کند.

API از تغییر مسیرها پیروی می کند. پاسخ سرور فناوری تبلیغات باید شامل یک هدر HTTP به نام Attribution-Reporting-Register-Trigger باشد که اطلاعات یک یا چند محرک ثبت شده را نشان می دهد. محتوای هدر باید با کد JSON باشد و شامل فیلدهای زیر باشد:

• داده های ماشه: داده هایی برای شناسایی رویداد ماشه (3 بیت برای کلیک، 1 بیت برای بازدید). باید یک عدد صحیح امضا شده 64 بیتی باشد که به صورت رشته فرمت شده است.

• اولویت راه‌اندازی (اختیاری): نشان‌دهنده اولویت این راه‌انداز در مقایسه با سایر محرک‌ها برای همان منبع انتساب است. باید یک عدد صحیح امضا شده 64 بیتی باشد که به صورت رشته فرمت شده است. برای جزئیات بیشتر در مورد چگونگی تأثیر اولویت بر گزارش، به بخش اولویت بندی مراجعه کنید.

• کلید Deduplication (اختیاری): برای شناسایی مواردی استفاده می شود که در آن یک ماشه چندین بار توسط یک پلت فرم فناوری تبلیغاتی یکسان، برای منبع انتساب یکسانی ثبت شده است. باید یک عدد صحیح امضا شده 64 بیتی باشد که به صورت رشته فرمت شده است.

• کلیدهای تجمیع (اختیاری): فهرستی از فرهنگ لغت که کلیدهای تجمیع را مشخص می کند و گزارش های انباشته باید دارای ارزش تجمیع شوند.

• مقادیر تجمیع (اختیاری): فهرستی از مقادیری که به هر کلید کمک می کند.

• فیلترها (اختیاری): برای فیلتر کردن محرک ها یا داده های ماشه استفاده می شود. برای جزئیات بیشتر، بخش فیلترهای ماشه را در این صفحه ببینید.

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

چندین فناوری تبلیغاتی می‌توانند با استفاده از تغییر مسیرها در قسمت Attribution-Reporting-Redirect یا تماس‌های متعدد با متد registerTrigger() یک رویداد ماشه را ثبت کنند. توصیه می‌کنیم از فیلد کلید deduplication استفاده کنید تا از قرار دادن محرک‌های تکراری در گزارش‌ها در مواردی که فناوری تبلیغاتی یکسان برای یک رویداد راه‌اندازی پاسخ‌های متعددی ارائه می‌دهد، خودداری کنید. در مورد نحوه و زمان استفاده از کلید حذف مجدد اطلاعات بیشتری کسب کنید.

راهنمای توسعه‌دهنده شامل نمونه‌هایی است که نحوه پذیرش ثبت ماشه را نشان می‌دهد.

مراحل زیر یک نمونه گردش کار را نشان می دهد:

1. Ad tech SDK API را فراخوانی می‌کند تا با استفاده از یک URI از پیش ثبت‌نام‌شده، ثبت راه‌اندازی را آغاز کند. برای اطلاعات بیشتر به ثبت نام برای یک حساب Sandbox حریم خصوصی مراجعه کنید.

   registerTrigger(
       Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
   

2. API درخواستی به https://adtech.example/attribution_trigger? AD_TECH_PROVIDED_METADATA .

3. سرور HTTPS این فناوری تبلیغاتی با سرصفحه هایی حاوی موارد زیر پاسخ می دهد:

   Attribution-Reporting-Register-Trigger: {
       "event_trigger_data": [{
       "trigger_data": "1122",
       // This returns 010 for click-through conversions (CTCs) and 0 for
       // view-through conversions (VTCs) in reports
       "priority": "3",
       "deduplication_key": "3344"
       }],
   }
   Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567
   

   توجه: فقط فناوری تبلیغاتی که تماس API را آغاز می‌کند، می‌تواند شرکا را در Attribution-Reporting-Redirect مشخص کند.

4. API برای هر URL مشخص شده در Attribution-Reporting-Redirect درخواست می کند. در این مثال، تنها یک URL مشخص شده است، بنابراین API یک درخواست به https://adtechpartner.example?app_install=567 ارسال می کند.

5. سرور HTTPS این فناوری تبلیغاتی با سرصفحه هایی حاوی موارد زیر پاسخ می دهد:

   Attribution-Reporting-Register-Trigger: {
   "event_trigger_data":[{
     "trigger_data": "5566",
     "priority": "3",
     "deduplication_key": "3344"
   }]
   }
   

   دو تریگر بر اساس درخواست های مراحل قبل ثبت می شود.

قابلیت های اسناد

بخش‌های زیر توضیح می‌دهند که چگونه API گزارش Attribution با محرک‌های تبدیل به منابع انتساب مطابقت دارد.

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

Attribution Reporting API از یک الگوریتم انتساب با اولویت منبع برای تطبیق یک محرک (تبدیل) به منبع انتساب استفاده می کند.

پارامترهای اولویت راه هایی را برای سفارشی کردن انتساب محرک ها به منابع ارائه می دهند:

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

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

فیلترهای ماشه ای

ثبت منبع و ماشه شامل ویژگی های اختیاری اضافی برای انجام موارد زیر است:

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

برای فیلتر کردن محرک‌های انتخابی، فناوری تبلیغات می‌تواند داده‌های فیلتر، متشکل از کلیدها و مقادیر را در طول ثبت منبع و ماشه مشخص کند. اگر کلید یکسانی برای منبع و ماشه مشخص شده باشد، در صورت خالی بودن تقاطع، ماشه نادیده گرفته می شود. به عنوان مثال، یک منبع می تواند "product": ["1234"] ، جایی که product کلید فیلتر و 1234 مقدار است. اگر فیلتر ماشه روی "product": ["1111"] تنظیم شده باشد، ماشه نادیده گرفته می شود. اگر product مطابق با کلید فیلتر ماشه وجود نداشته باشد، فیلترها نادیده گرفته می شوند.

سناریوی دیگری که در آن پلتفرم‌های فناوری تبلیغات ممکن است بخواهند به طور انتخابی محرک‌ها را فیلتر کنند، مجبور کردن یک پنجره انقضا کوتاه‌تر است. در ثبت ماشه، یک فناوری تبلیغاتی می‌تواند (در چند ثانیه) یک پنجره بازبینی از زمانی که تبدیل اتفاق افتاد را مشخص کند. به عنوان مثال، یک پنجره بازبینی 7 روزه به این صورت تعریف می شود: "_lookback_window": 604800 // 7d

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

توجه: منطق فیلتر نگاه و عملکرد توصیف شده در Q124 قابل اجرا خواهد بود. می‌توانید جزئیات بیشتری در مورد زمان انتشار پیدا کنید . منطق قبلی مستلزم این بود که پنجره‌های نگاه به ساعت، هم در سمت مبدا و هم از طرف ماشه مشخص شوند. این منطق ویژگی به روز شده با عقب ناسازگار است، به این معنی که منابعی که از کلید قبلی "_lookback_window" استفاده می کنند با موفقیت ثبت نمی شوند.

پلتفرم‌های فناوری تبلیغات همچنین می‌توانند داده‌های راه‌اندازی را بر اساس داده‌های رویداد منبع انتخاب کنند. برای مثال، source_type به طور خودکار توسط API به عنوان navigation یا event ایجاد می‌شود. در طول ثبت ماشه، trigger_data می توان به عنوان یک مقدار برای "source_type": ["navigation"] و به عنوان یک مقدار متفاوت برای "source_type": ["event"] تنظیم کرد.

در صورت صحت هر یک از موارد زیر، راه‌اندازها از گزارش‌های سطح رویداد حذف می‌شوند:

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

انتساب پس از نصب

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

API می‌تواند با اجازه دادن به فناوری‌های تبلیغاتی برای تنظیم دوره انتساب پس از نصب، از این مورد استفاده پشتیبانی کند:

• هنگام ثبت منبع انتساب، یک پنجره انتساب نصب را مشخص کنید که در طی آن نصب ها مورد انتظار است (معمولاً 2-7 روز، محدوده پذیرفته شده 1 تا 30 روز). این پنجره زمانی را به صورت چند ثانیه مشخص کنید.
• هنگام ثبت منبع انتساب، یک پنجره انحصاری انتساب پس از نصب را مشخص کنید که در آن رویدادهای راه‌اندازی پس از نصب باید با منبع انتسابی که باعث نصب شده است مرتبط شود (معمولاً 7-30 روز، محدوده پذیرفته شده 0 تا 30 روز). این پنجره زمانی را به صورت چند ثانیه مشخص کنید.
• Attribution Reporting API زمانی که نصب برنامه اتفاق می‌افتد اعتبارسنجی می‌کند و به صورت داخلی نصب را به منبع انتساب با اولویت منبع نسبت می‌دهد. با این حال، نصب برای فن‌آوری‌های تبلیغاتی ارسال نمی‌شود و در محدودیت‌های نرخ مربوطه پلتفرم حساب نمی‌شود.
• اعتبار سنجی نصب برنامه برای هر برنامه دانلود شده در دسترس است.
• هر راه‌اندازی آتی که در پنجره انتساب پس از نصب اتفاق می‌افتد، تا زمانی که منبع انتساب واجد شرایط باشد، به همان منبع انتساب نصب معتبر نسبت داده می‌شود.

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

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

رویداد	روزی که رویداد رخ می دهد	یادداشت ها
1 را کلیک کنید	1	install_attribution_window روی 172800 (2 روز) و post_install_exclusivity_window روی 864000 (10 روز) تنظیم شده است.
نصب تایید شده	2	ویژگی های داخلی API نصب های تأیید شده را تأیید می کند ، اما این نصب ها محرک محسوب نمی شوند. بنابراین گزارشی در این مرحله ارسال نمی شود.
ماشه 1 (اولین باز)	2	اولین ماشه توسط فناوری تبلیغات ثبت شد. در این مثال، یک اولین باز را نشان می دهد اما می تواند هر نوع ماشه ای باشد. منتسب به کلیک 1 (منطبق با انتساب نصب تأیید شده).
روی 2 کلیک کنید	4	از مقادیر یکسانی برای install_attribution_window و post_install_exclusivity_window استفاده می کند.
Trigger 2 (پست نصب)	5	عامل دوم توسط فناوری تبلیغات ثبت شده است. در این مثال، یک تبدیل پس از نصب را مانند خرید نشان می دهد. منتسب به کلیک 1 (منطبق با انتساب نصب تأیید شده). کلیک 2 کنار گذاشته شده است و برای انتساب بعدی واجد شرایط نیست.

لیست زیر نکات دیگری را در مورد انتساب پس از نصب ارائه می دهد:

• اگر نصب تأیید شده در تعداد روزهای مشخص شده توسط install_attribution_window انجام نشود، انتساب پس از نصب اعمال نمی‌شود.
• نصب های تأیید شده توسط فناوری های تبلیغاتی ثبت نمی شوند و در گزارش ها ارسال نمی شوند. آنها در مقابل محدودیت های نرخ یک فناوری تبلیغات حساب نمی شوند. نصب‌های تأیید شده فقط برای شناسایی منبع انتساب استفاده می‌شوند که به نصب اعتبار داده شده است.
• در مثال جدول قبل، تریگر 1 و تریگر 2 به ترتیب اولین تبدیل باز و تبدیل پس از نصب را نشان می دهند. با این حال، پلتفرم های فناوری تبلیغات می توانند هر نوع محرکی را ثبت کنند. به عبارت دیگر، اولین ماشه نباید اولین ماشه باز باشد.
• اگر پس از انقضای post_install_exclusivity_window ، محرک‌های بیشتری ثبت شوند، با این فرض که منقضی نشده است و به محدودیت‌های نرخ خود نرسیده است، کلیک 1 همچنان واجد شرایط است.
  • اگر منبع انتساب با اولویت بالاتر ثبت شده باشد، کلیک 1 همچنان ممکن است از دست برود، یا نادیده گرفته شود.
• اگر برنامه تبلیغ‌کننده حذف نصب و مجدداً نصب شود، نصب مجدد به‌عنوان یک نصب تأیید شده جدید محاسبه می‌شود.
• اگر کلیک 1 در عوض یک رویداد مشاهده بود، هر دو راه‌انداز «اولین باز» و پس از نصب همچنان به آن نسبت داده می‌شوند. API انتساب را به یک راه‌انداز در هر نما محدود می‌کند، مگر در مورد انتساب پس از نصب که حداکثر دو راه‌انداز در هر نما مجاز است. در مورد انتساب پس از نصب، فناوری تبلیغات می‌تواند ۲ پنجره گزارش متفاوت (در ۲ روز یا در انقضای منبع) دریافت کند.

همه ترکیبی از مسیرهای ماشه مبتنی بر برنامه و وب پشتیبانی می شوند

Attribution Reporting API انتساب مسیرهای راه‌اندازی زیر را در یک دستگاه Android فعال می‌کند:

• برنامه به برنامه: کاربر یک تبلیغ را در یک برنامه می بیند، سپس در آن برنامه یا برنامه نصب شده دیگری تبدیل می کند.
• برنامه به وب: کاربر یک تبلیغ را در یک برنامه می بیند، سپس در مرورگر موبایل یا برنامه تبدیل می کند.
• وب به برنامه: کاربر یک تبلیغ را در مرورگر موبایل یا برنامه می بیند، سپس در یک برنامه تبدیل می کند.
• وب به وب: کاربر یک تبلیغ را در مرورگر تلفن همراه یا برنامه می بیند، سپس در همان مرورگر یا مرورگر دیگری در همان دستگاه تبدیل می کند.

ما به مرورگرهای وب اجازه می‌دهیم از ویژگی‌های جدید تحت وب پشتیبانی کنند، مانند عملکردی که شبیه به Privacy Sandbox برای Web's Attribution Reporting API است، که می‌تواند APIهای Android را برای فعال کردن انتساب در برنامه و وب فراخوانی کند.

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

برای یک منبع انتساب، چندین محرک را اولویت بندی کنید

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

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

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

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

توجه: محرک‌های با اولویت پایین‌تر که قبلاً گزارش شده‌اند، همیشه بودجه را مصرف می‌کنند.

به چندین فناوری تبلیغات اجازه دهید منابع یا محرک‌های انتساب را ثبت کنند

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

تبلیغ‌کنندگانی که می‌خواهند از یک شخص ثالث برای انجام کپی‌برداری بین شبکه‌ای استفاده کنند، می‌توانند با استفاده از تکنیکی شبیه به زیر به این کار ادامه دهند:

• راه اندازی یک سرور داخلی برای ثبت نام و دریافت گزارش از API.
• ادامه استفاده از شریک اندازه گیری تلفن همراه موجود.

منابع انتساب

تغییر مسیرهای منبع انتساب در روش registerSource() پشتیبانی می شود:

1. فناوری تبلیغاتی که متد registerSource() را فراخوانی می‌کند، می‌تواند یک فیلد Attribution-Reporting-Redirect اضافی را در پاسخ خود ارائه دهد، که نشان‌دهنده مجموعه URL‌های تغییر مسیر شرکت فناوری تبلیغات شریک است.
2. سپس API URL های تغییر مسیر را فراخوانی می کند تا منبع انتساب توسط متخصصان تبلیغات شریک ثبت شود.

آدرس‌های اینترنتی فناوری تبلیغات شریک چندگانه را می‌توان در قسمت Attribution-Reporting-Redirect فهرست کرد، و شرکت‌های فناوری تبلیغات شریک نمی‌توانند قسمت Attribution-Reporting-Redirect خود را مشخص کنند.

API همچنین به فناوری‌های تبلیغاتی مختلف اجازه می‌دهد تا هر call registerSource() انجام دهند.

محرک ها

برای ثبت تریگر، اشخاص ثالث به روشی مشابه پشتیبانی می‌شوند: فناوری‌های تبلیغاتی می‌توانند از فیلد Attribution-Reporting-Redirect اضافی استفاده کنند، یا هر کدام می‌توانند متد registerTrigger() را فراخوانی کنند.

هنگامی که یک تبلیغ‌کننده از فناوری‌های تبلیغاتی متعدد برای ثبت یک رویداد محرک استفاده می‌کند، باید از یک کلید حذف تکراری استفاده شود. کلید deduplication برای ابهام‌زدایی از این گزارش‌های مکرر از همان رویداد ثبت‌شده توسط همان پلت‌فرم فناوری تبلیغاتی استفاده می‌کند. به عنوان مثال، یک فناوری تبلیغاتی می‌تواند از SDK خود مستقیماً با API تماس بگیرد تا یک راه‌انداز را ثبت کند و URL خود را در قسمت تغییر مسیر تماس یک فناوری تبلیغاتی دیگر قرار دهد. اگر کلید حذف مجدد ارائه نشده باشد، ممکن است محرک های تکراری به عنوان منحصر به فرد به هر فناوری تبلیغاتی گزارش شود.

محرک های تکراری را مدیریت کنید

یک فناوری تبلیغاتی ممکن است یک ماشه را چندین بار با API ثبت کند. سناریوها شامل موارد زیر است:

• کاربر یک عمل (تریگر) را چندین بار انجام می دهد. به عنوان مثال، کاربر یک محصول را چندین بار در یک پنجره گزارش یکسان مرور می کند.
• برنامه تبلیغ‌کننده از چند SDK برای اندازه‌گیری تبدیل استفاده می‌کند که همگی به یک فناوری تبلیغات هدایت می‌شوند. برای مثال، اپلیکیشن تبلیغ‌کننده از دو شریک اندازه‌گیری، MMP #1 و MMP #2 استفاده می‌کند. هر دو MMP به فناوری تبلیغات شماره 3 هدایت می شوند. هنگامی که یک ماشه اتفاق می افتد، هر دو MMP آن ماشه را با API گزارش Attribution ثبت می کنند. سپس فناوری تبلیغات شماره 3 دو تغییر مسیر جداگانه - یکی از MMP شماره 1 و دیگری از MMP شماره 2 - برای همان ماشه دریافت می کند.

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

روش پیشنهادی: کلید deduplication

روش پیشنهادی این است که برنامه تبلیغ‌کننده یک کلید تکراری منحصر به فرد را به هر فناوری تبلیغات یا SDK که برای اندازه‌گیری تبدیل استفاده می‌کند، ارسال کند. هنگامی که یک تبدیل اتفاق می افتد، برنامه یک کلید حذف مجدد را به فناوری های تبلیغاتی یا SDK ها ارسال می کند. آن فناوری‌های تبلیغاتی یا SDK‌ها سپس با استفاده از پارامتری در آدرس‌های اینترنتی مشخص‌شده در Attribution-Reporting-Redirect کلید حذف‌سازی را به تغییرمسیرها ارسال می‌کنند.

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

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

روش جایگزین: فن‌آوران تبلیغات در مورد انواع محرک هر تبلیغ‌کننده توافق دارند

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

فن‌آوری‌های تبلیغاتی که تماس ثبت‌نام راه‌انداز را آغاز می‌کنند - برای مثال، SDKها - شامل یک پارامتر در URLهای مشخص شده در Attribution-Reporting-Redirect هستند، مانند duplicate_trigger_id . این پارامتر duplicate_trigger_id می‌تواند شامل اطلاعاتی مانند نام SDK و نوع راه‌انداز برای آن تبلیغ‌کننده باشد. سپس فناوری‌های تبلیغاتی می‌توانند زیرمجموعه‌ای از این محرک‌های تکراری را به گزارش‌های سطح رویداد ارسال کنند. فناوری‌های تبلیغاتی همچنین می‌توانند این duplicate_trigger_id در کلیدهای تجمیع خود بگنجانند.

نمونه اسناد بین شبکه ای

در مثالی که در این بخش توضیح داده شد، تبلیغ‌کننده از دو پلتفرم فناوری تبلیغاتی (Ad tech A و Ad tech B) و یک شریک اندازه‌گیری (MMP) استفاده می‌کند.

برای شروع، Ad tech A، Ad tech B و MMP باید ثبت نام خود را تکمیل کنند تا از Attribution Reporting API استفاده کنند. برای اطلاعات بیشتر به ثبت نام برای یک حساب Sandbox حریم خصوصی مراجعه کنید.

فهرست زیر مجموعه‌ای فرضی از اقدامات کاربر را ارائه می‌کند که هرکدام به فاصله یک روز از هم انجام می‌شوند، و اینکه چگونه API گزارش انتساب آن اقدامات را با توجه به Ad tech A، Ad tech B و MMP انجام می‌دهد:

روز 1: کلیک کاربر روی تبلیغی که توسط Ad tech A ارائه شده است

Ad tech A با URI خود registerSource() فرا می خواند. API درخواستی به URI می‌کند و کلیک با ابرداده از پاسخ سرور Ad tech A ثبت می‌شود.

Ad tech A همچنین شامل URI MMP در سرصفحه Attribution-Reporting-Redirect می شود. API درخواستی را به URI MMP ارسال می کند و کلیک با فراداده از پاسخ سرور MMP ثبت می شود.

روز 2: کلیک کاربر روی تبلیغی که توسط Ad tech B ارائه شده است

Ad tech B، registerSource() با URI خود فرا می خواند. API درخواستی به URI می‌کند و کلیک با ابرداده از پاسخ سرور Ad tech B ثبت می‌شود.

مانند Ad tech A، Ad tech B نیز URI MMP را در هدر Attribution-Reporting-Redirect گنجانده است. API درخواستی به URI MMP می دهد و کلیک با فراداده از پاسخ سرور MMP ثبت می شود.

روز 3: کاربر آگهی ارائه شده توسط Ad tech A را مشاهده می کند

API به همان روشی که در روز اول انجام داد پاسخ می‌دهد، با این تفاوت که یک نما برای Ad tech A و MMP ثبت می‌شود.

روز 4: کاربر برنامه را نصب می کند که از MMP برای اندازه گیری تبدیل استفاده می کند

MMP registerTrigger() با URI خود فرا می خواند. API یک درخواست به URL ارسال می کند و تبدیل با فراداده از پاسخ سرور MMP ثبت می شود.

MMP همچنین شامل URI برای Ad tech A و Ad tech B در سرصفحه Attribution-Reporting-Redirect است. API به سرورهای Ad tech A و Ad tech B درخواست می کند و تبدیل مطابق با فراداده پاسخ های سرور ثبت می شود.

نمودار زیر روند شرح داده شده در لیست قبلی را نشان می دهد:

نمونه ای از نحوه پاسخ API گزارش Attribution به مجموعه ای از اقدامات کاربر.

Attribution به شرح زیر عمل می کند:

• Ad tech A اولویت کلیک‌ها را بالاتر از بازدیدها تنظیم می‌کند و بنابراین نصب منتسب به کلیک در روز اول را دریافت می‌کند.
• Ad tech B نصب منتسب در روز 2 را دریافت می کند.
• MMP اولویت کلیک‌ها را بالاتر از بازدیدها تنظیم می‌کند و نصب منتسب به کلیک در روز 2 را دریافت می‌کند. کلیک روز 2 بالاترین اولویت، آخرین رویداد تبلیغاتی است.

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

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

جریان سطح بالا

1. هنگام ثبت منبع، شبکه فناوری تبلیغات ارائه دهنده کلیدهای تجمیع منبع خود را به اشتراک می گذارد.
2. هنگام ثبت ماشه، تبلیغ‌کننده یا شریک اندازه‌گیری انتخاب می‌کند که از کدام قطعات کلیدی سمت منبع استفاده کند و پیکربندی انتساب آن‌ها را مشخص می‌کند.
3. Attribution بر اساس پیکربندی انتساب، کلیدهای مشترک، و هر منبعی است که واقعاً توسط آن تبلیغ‌کننده یا شریک اندازه‌گیری ثبت شده است (مثلاً از شبکه فناوری تبلیغاتی دیگری که تغییر مسیرها را فعال کرده است).
4. اگر راه‌انداز به منبعی از فناوری تبلیغات ارائه‌دهنده بدون تغییر مسیر نسبت داده شود، تبلیغ‌کننده یا شریک اندازه‌گیری می‌تواند گزارش جمع‌آوری‌شده‌ای دریافت کند که منبع و بخش‌های کلیدی راه‌انداز تعریف‌شده در مرحله ۲ را ترکیب می‌کند.

ثبت منبع

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

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

ماشه ثبت نام

در ثبت نام Trigger ، اندازه گیری AD Tech انتخاب می کند که کدام یک از قسمت های اصلی منبع را برای هر قطعه کلید ماشه اعمال می کند ، از جمله هر نوع به اشتراک گذاشته شده توسط تکنیک های تبلیغاتی.

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

انتساب

API گزارشگر انتساب نسبت به منبع اصلی و برتر برای فناوری اندازه گیری تبلیغات بر اساس پیکربندی انتساب آنها ، کلیدهای مشترک و هر منبعی که ثبت کرده اند ، انجام می دهد. به عنوان مثال:

• کاربر روی تبلیغات ارائه شده توسط Ad Techs A ، B ، C و D. کلیک کرد و کاربر سپس برنامه تبلیغ کننده را نصب کرد که از یک شریک AD Tech Ad (MMP) استفاده می کند.
• AD Tech A منابع خود را به MMP هدایت می کند.
• AD Techs B و C تغییر مسیر نمی دهند ، اما کلیدهای جمع آوری آنها را به اشتراک می گذارند.
• Ad Tech D نه تغییر مسیر و نه کلیدهای جمع آوری را به اشتراک می گذارد.

MMP یک منبع از Ad Tech A را ثبت می کند و پیکربندی انتساب را تعریف می کند که شامل Ad Tech B و Ad Tech D. D. است.

انتساب برای MMP اکنون شامل موارد زیر است:

• AD Tech A ، از آنجا که MMP منبع تغییر مسیر آن Ad Tech را ثبت کرد.
• Ad Tech B ، از آنجا که AD Tech B کلیدهای مشترک و MMP آن را در پیکربندی انتساب آنها گنجانده است.

انتساب برای MMP شامل موارد زیر نیست:

• AD Tech C ، از آنجا که MMP آن را در پیکربندی انتساب آنها درج نکرد.
• AD Tech D ، از آنجا که آنها کلیدهای جمع آوری را تغییر نمی دهند و به اشتراک نمی گذارند.

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

اشکال زدایی

برای پشتیبانی از اشکال زدایی برای انتساب متقابل شبکه بدون تغییر مسیر ، یک زمینه اضافی ، shared_debug_key ، برای تکنیک های تبلیغاتی در دسترس است تا ثبت نام منبع را تنظیم کند. در صورت ثبت نام منبع اصلی ، در هنگام ثبت ماشه برای انتساب شبکه متقابل بدون تغییر مسیر ، منبع مشتق شده مربوطه را نیز به عنوان debug_key تنظیم می کند. این کلید اشکال زدایی در گزارش های رویداد و کل به عنوان source_debug_key پیوست شده است.

این ویژگی اشکال زدایی فقط برای انتساب شبکه متقابل بدون تغییر مسیر تحت سناریوهای زیر پشتیبانی می شود:

• اندازه گیری برنامه به برنامه در جایی که ADID مجاز است
• برنامه به اندازه گیری وب که در آن ADID مجاز است و هم در منبع برنامه و هم در ماشه وب مطابقت دارد
• اندازه گیری وب به وب (در همان برنامه مرورگر) وقتی ar_debug `در هر دو منبع و ماشه وجود دارد

کشف کلیدی برای انتساب متقابل شبکه بدون تغییر مسیر

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

هنگامی که یک MMP از خدمات جمع آوری برای تولید گزارش های خلاصه برای کمپین هایی که شامل منابع مشتق شده است ، پرس و جو می کند ، خدمات جمع آوری نیاز به MMP دارد تا لیست کلیدهای ممکن را به عنوان ورودی برای کار تجمع مشخص کند. در بعضی موارد ، لیست کلیدهای جمع آوری منبع بالقوه ممکن است بسیار بزرگ یا ناشناخته باشد. لیست های بزرگی از کلیدهای ممکن برای ردیابی چالش برانگیز هستند و همچنین احتمالاً برای پردازش کاملاً پیچیده و پرهزینه هستند. به مثال های زیر توجه کنید:

• لیست تمام کلیدهای ممکن زیاد است:
  • یک شبکه تبلیغاتی در حال اجرای یک ابتکار پیچیده دستیابی کاربر است که شامل 20 کمپین ، هر یک با 10 گروه تبلیغاتی است و هر گروه تبلیغاتی با 5 خلاق که هر هفته بر اساس عملکرد تازه می شوند.
• لیست تمام کلیدهای ممکن ناشناخته است:
  • یک شبکه تبلیغاتی در حال ارائه تبلیغات در بسیاری از برنامه های تلفن همراه است که در آن لیست کامل شناسه برنامه ناشر در راه اندازی کمپین مشخص نیست.
  • یک تبلیغ کننده در حال کار در چندین شبکه تبلیغاتی در خدمت است که در ثبت نام منبع به MMP هدایت نمی شوند. هر شبکه تبلیغاتی دارای ساختار و مقادیر کلیدی متفاوتی است که ممکن است از قبل با MMP به اشتراک نگذاشته باشد.

با معرفی کلیدی کشف:

• سرویس جمع آوری دیگر نیازی به شمارش کامل کلیدهای تجمع احتمالی ندارد.
• به جای اینکه لیست کامل کلیدهای ممکن را مشخص کنید ، یک MMP می تواند یک مجموعه کلیدهای خالی (یا جزئی خالی) ایجاد کرده و یک آستانه را تنظیم کند ، به طوری که فقط کلیدهای (بدون پیش بینی) با مقادیر بیش از آستانه درج شده است. خروجی
• MMP گزارش خلاصه ای را دریافت می کند که شامل مقادیر پر سر و صدا برای کلیدهایی است که مقادیر آن را بالاتر از آستانه تنظیم می کنند. این گزارش همچنین ممکن است شامل کلیدهایی باشد که هیچ مشارکت کاربر واقعی ندارند و صرفاً بدون استفاده هستند.
• MMP از قسمت x_network_bit_mapping در ثبت Trigger استفاده می کند تا تعیین کند که کدام فناوری تبلیغی با کدام کلید مطابقت دارد.
• MMP سپس می تواند برای درک مقادیر موجود در کلید منبع با فناوری تبلیغاتی مناسب تماس بگیرد.

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

توجه: این ویژگی در مرحله پیشنهاد است و هنوز برای آزمایش در دسترس نیست. بازخورد و نظرات شما تشویق می شود .

تغییر مسیر زنجیره ای دیزی

با ارائه چندین هدف Attribution-Reporting-Redirect در یک منبع یا ثبت نام HTTPS Server-Response ، یک فناوری تبلیغی می تواند از API گزارش دهی انتساب برای انجام چندین منبع استفاده کند و با یک تماس API ثبت نام واحد ثبت نام کند.

در پاسخ سرور ، فناوری AD همچنین می تواند یک هدر Location (302 تغییر مسیر) با URL را شامل شود که به نوبه خود منجر به ثبت نام دیگری می شود ، تا حد مشخصی.

هر دو نوع هدست اختیاری هستند و در صورت عدم نیاز به تغییر مسیر ، هیچ یک از آنها قابل ارائه نیست. ممکن است یک یا هر دو نوع هدست ارائه شود. درخواست های ثبت نام منبع و ماشه (از جمله تغییر مسیر) در صورت خرابی شبکه دوباره انجام می شوند. برای جلوگیری از تأثیر قابل توجه بر روی دستگاه ، تعداد قیام در هر درخواست به تعداد ثابت محدود می شود.

تغییر مسیر برای RegisterWebSource و RegisterWebTrigger مورد استفاده مرورگرها پذیرفته نمی شوند. جزئیات بیشتر را می توان در راهنمای Cross Web و Guide Appormation یافت.

مشاهده داده های اندازه گیری در گزارش های انتساب

API گزارش انتساب انواع گزارش های زیر را امکان پذیر می کند ، که بعداً در این صفحه با جزئیات بیشتری توضیح داده شده است:

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

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

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

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

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

گزارش سطح رویداد شامل داده هایی مانند موارد زیر است:

• مقصد: نام بسته برنامه تبلیغاتی یا ETLD+1 که در آن ماشه اتفاق افتاده است
• شناسه منبع Attribution: همان شناسه منبع انتساب که برای ثبت یک منبع انتساب استفاده شده است
• نوع ماشه: بسته به نوع منبع انتساب ، 1 یا 3 بیت از داده های ماشه کم وفاداری

مکانیسم های حفظ حریم خصوصی برای همه گزارش ها اعمال می شود

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

محدودیت در تعداد تکنیک های تبلیغاتی

محدودیت هایی در تعداد تکنیک های تبلیغاتی وجود دارد که می توانند گزارش های API را ثبت یا دریافت کنند ، با یک پیشنهاد فعلی از موارد زیر:

• 100 فناوری تبلیغاتی با منابع انتساب در هر برنامه منبع ، برنامه مقصد ، 30 روز ، دستگاه.
• 10 تکنیک تبلیغاتی با محرک های نسبت داده شده در هر برنامه منبع ، برنامه مقصد ، 30 روز ، دستگاه.
• 20 فناوری تبلیغی می توانند یک منبع یا ماشه انتساب واحد را ثبت کنند (از طریق Attribution-Reporting-Redirect )

محدودیت در تعداد مقصد های منحصر به فرد

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

• در تمام منابع ثبت شده ، در تمام تکنیک های تبلیغاتی ، API بیش از 200 مقصد منحصر به فرد ، در هر برنامه منبع ، در هر دقیقه پشتیبانی نمی کند.
• در تمام منابع ثبت شده ، برای یک فناوری تبلیغاتی واحد ، API بیش از 50 مقصد منحصر به فرد ، در هر برنامه منبع ، در هر دقیقه پشتیبانی نمی کند. این حد مانع از استفاده از یک فناوری تبلیغاتی از کل بودجه از حد نرخ قبلاً ذکر شده می شود.

منابع منقضی شده به محدودیت نرخ حساب نمی شوند.

یک منشأ گزارش در هر برنامه منبع در روز

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

سناریوی زیر را در نظر بگیرید ، جایی که یک فناوری تبلیغاتی واحد می خواهد برای ثبت منابع در یک برنامه ناشر ، برای یک دستگاه واحد ، از منشاء گزارش دهی چندگانه استفاده کند.

1. گزارش Ad Tech A's Origin 1 منبع در برنامه B ثبت می کند
2. 12 ساعت بعد ، گزارش گزارش AD Tech A در تلاش برای ثبت منبع در برنامه B

منبع دوم ، برای گزارش گزارش Ad Tech A در Origin 2 ، توسط API رد می شود. گزارش گزارش AD Tech A در Origin 2 قادر به ثبت موفقیت آمیز منبع در همان دستگاه در برنامه B نیست.

Cooldown و محدودیت نرخ

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

پیشنهاد فعلی محدود کردن هر فناوری تبلیغاتی به 100 محرک نسبت داده شده در هر برنامه منبع ، برنامه مقصد ، 30 روز ، دستگاه است.

تعداد مقصد های منحصر به فرد

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

پیشنهاد فعلی محدود کردن هر فناوری تبلیغاتی به 100 مقصد مجزا با منابع غیر افزایش یافته در هر برنامه منبع است.

مکانیسم های حفظ حریم خصوصی برای گزارش های سطح رویداد اعمال می شود

وفاداری محدود داده های ماشه

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

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

چارچوب سر و صدای حریم خصوصی دیفرانسیل

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

سر و صدا در مورد اینکه آیا یک رویداد منبع انتساب به حقیقت گزارش شده است ، اعمال می شود. یک منبع انتساب در دستگاه با احتمال 1-p $ ثبت شده است که منبع انتساب به صورت عادی ثبت شده است ، و با احتمال P $ P $ که دستگاه به طور تصادفی در بین تمام حالت های خروجی ممکن API انتخاب می کند (از جمله گزارش دادن به هیچ وجه ، یا گزارش چندین گزارش جعلی).

پاسخ k-randomized الگوریتمی است که در صورت رضایت از معادله زیر ، اپسیلون متفاوت است:

\[ p = \frac{k}{k + e^ε - 1} \]

برای مقادیر کم ε ، خروجی واقعی توسط مکانیسم پاسخ k-randomized محافظت می شود. پارامترهای دقیق نویز در حال انجام است و بر اساس بازخورد در معرض تغییر قرار می گیرد ، با یک پیشنهاد فعلی از موارد زیر:

• P = 0.24 ٪ برای منابع ناوبری
• P = 0.00025 ٪ برای منابع رویداد

محدودیت در محرک های موجود (تبدیل)

محدودیت هایی در تعداد محرک ها در هر منبع انتساب وجود دارد ، با یک پیشنهاد فعلی از موارد زیر:

• 1-2 محرک برای منابع انتساب نمای تبلیغ (2 محرک فقط در مورد انتساب پس از نصب در دسترس است)
• 3 محرک برای منابع انتساب AD کلیک کنید

توجه: این رفتار پیش فرض API را برای تعداد ویژگی های هر منبع با استفاده از گزارش در سطح رویداد توصیف می کند. با معرفی گزارش های انعطاف پذیر در سطح رویداد در اکتبر 2023 ، AD Techs اکنون می توانند این بعد گزارش های خود را بر اساس آنچه برای مورد استفاده آنها بهتر است ، پیکربندی کنند.

ویندوزهای زمان خاص برای ارسال گزارش ها (رفتار پیش فرض)

گزارش های سطح رویداد برای منابع انتساب نمای تبلیغ 1 ساعت پس از انقضاء منبع ارسال می شود. این تاریخ انقضا را می توان پیکربندی کرد ، اما نمی تواند کمتر از 1 روز یا بیشتر از 30 روز باشد. اگر دو محرک به یک منبع انتساب نمای تبلیغ (از طریق انتساب پس از نصب ) نسبت داده شود) ، گزارش های سطح رویداد را می توان در فواصل پنجره گزارش مشخص شده به شرح زیر ارسال کرد.

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

• 2 روز: دستگاه تمام محرک هایی را که حداکثر 2 روز پس از ثبت منبع انتساب رخ داده است ، جمع می کند. این گزارش 2 روز و 1 ساعت پس از ثبت منبع انتساب ارسال می شود.
• 7 روز: دستگاه تمام محرک هایی را که بیش از 2 روز رخ داده است جمع می کند اما بیش از 7 روز پس از ثبت منبع انتساب نیست. این گزارش 7 روز و 1 ساعت پس از ثبت منبع انتساب ارسال می شود.
• مدت زمان سفارشی ، تعریف شده توسط ویژگی "انقضا" یک منبع انتساب. این گزارش 1 ساعت پس از زمان انقضا مشخص شده ارسال می شود. این مقدار نمی تواند کمتر از 1 روز یا بیشتر از 30 روز باشد.

توجه: این توصیف رفتار پیش فرض API برای ویندوزهای گزارش در سطح رویداد است. با معرفی گزارش های انعطاف پذیر در سطح رویداد در اکتبر 2023 ، AD Techs اکنون می توانند این بعد گزارش های خود را بر اساس آنچه برای مورد استفاده آنها بهتر است ، پیکربندی کنند.

پیکربندی سطح رویداد انعطاف پذیر

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

این انعطاف پذیری اضافی در دو مرحله به API گزارش انتساب معرفی می شود:

• فاز 1: پیکربندی سطح رویداد انعطاف پذیر Lite
  • این نسخه زیر مجموعه ای از ویژگی های کامل را ارائه می دهد و می تواند به طور مستقل از فاز 2 استفاده شود.
• فاز 2: نسخه کامل پیکربندی سطح رویداد انعطاف پذیر

فاز 1 (سطح رویداد انعطاف پذیر Lite) می تواند مورد استفاده قرار گیرد:

• با مشخص کردن تعداد ویندوزهای گزارش دهنده ، فرکانس گزارش ها را تغییر دهید
• تعداد ویژگی های ثبت نام منبع را تغییر دهید
• با کاهش پارامترهای فوق ، میزان سر و صدای کل را کاهش دهید
• به جای استفاده از پیش فرض ، ویندوز گزارش را پیکربندی کنید

فاز 2 (سطح رویداد انعطاف پذیر کامل) می تواند برای انجام تمام قابلیت های موجود در فاز 1 و:

• در یک گزارش ، کاردینال بودن داده های ماشه را تغییر دهید
• با کاهش کاردینال بودن داده های ماشه ، میزان سر و صدای کل را کاهش دهید

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

علاوه بر تنظیم پویا سطح نویز بر اساس پیکربندی انتخاب شده یک فناوری تبلیغاتی ، ما برای جلوگیری از هزینه های محاسبات بزرگ و تنظیمات با حالت های خروجی بیش از حد ، محدودیت های پارامتر خواهیم داشت (جایی که نویز به میزان قابل توجهی افزایش می یابد). در اینجا نمونه ای از محدودیت ها آورده شده است. بازخورد در مورد [پیشنهاد طراحی] [50] تشویق می شود:

• حداکثر 20 گزارش کل ، در سطح جهان و در هر ماشه_داتا
• حداکثر 5 ویندوز گزارش ممکن در هر Trigger_Data
• حداکثر 32 کاردینال بودن داده های ماشه (برای مرحله 1 قابل اجرا نیست: سطح رویداد انعطاف پذیر Lite)

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

توجه: فاز 1 (سطح رویداد انعطاف پذیر Lite) در اکتبر 2023 در بتا منتشر شد. فاز 2 (سطح رویداد کامل انعطاف پذیر) برای انتشار در بتا بعداً در Q1 2024 برنامه ریزی شده است.

گزارش های قابل جمع شدن

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

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

• گزارش برای مقادیر ماشه مانند درآمد
• رسیدگی به انواع ماشه بیشتر

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

طراحی کلی نحوه تهیه API گزارش انتساب ، گزارش های قابل جمع ، که در نمودار نشان داده شده است ، به شرح زیر است:

1. این دستگاه گزارش های قابل رمزگذاری شده را به فناوری تبلیغاتی ارسال می کند. در یک محیط تولید ، فناوری های تبلیغاتی نمی توانند مستقیماً از این گزارش ها استفاده کنند.
2. فناوری تبلیغاتی دسته ای از گزارش های قابل جمع را برای جمع آوری به خدمات جمع آوری ارسال می کند.
3. سرویس جمع آوری مجموعه ای از گزارش های قابل جمع ، رمزگشایی و جمع آوری آنها را می خواند.
4. مصالح نهایی در یک گزارش خلاصه به فناوری تبلیغاتی ارسال می شوند.

فرآیندی که API گزارشگر انتساب برای تهیه و ارسال گزارش های قابل جمع از آن استفاده می کند.

گزارش های قابل جمع حاوی داده های زیر مربوط به منابع انتساب است:

• مقصد: نام بسته برنامه یا URL ETLD+1 Web که در آن ماشه اتفاق افتاده است.
• تاریخ: تاریخی که رویداد نمایش داده شده توسط منبع انتساب رخ داده است.
• Payload: مقادیر ماشه ، جمع آوری شده به عنوان جفت کلید/ارزش رمزگذاری شده ، که در سرویس جمع آوری قابل اعتماد برای محاسبه تجمع استفاده می شود.

خدمات تجمیع

خدمات زیر قابلیت جمع آوری داده ها و محافظت در برابر دسترسی غیرمجاز به داده های جمع شده را ارائه می دهد ..

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

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

سرویس تجمیع

سیستم عامل های AD Tech از قبل باید یک سرویس جمع آوری را که مبتنی بر باینری های ارائه شده توسط Google است ، مستقر کنند.

این سرویس جمع آوری در یک محیط اجرای قابل اعتماد (TEE) که در ابر برگزار می شود ، فعالیت می کند. یک TEE مزایای امنیتی زیر را ارائه می دهد:

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

این مزایای امنیتی باعث می شود که یک سرویس جمع آوری برای انجام عملیات حساس مانند دسترسی به داده های رمزگذاری شده ایمن تر شود.

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

سرویس مدیریت کلیدی

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

حسابداری گزارش قابل جمع شدن

این سرویس چند بار سرویس جمع آوری یک فناوری تبلیغاتی را به یک ماشه خاص دسترسی می دهد - که می تواند حاوی کلیدهای جمع آوری باشد - و دسترسی به تعداد مناسب رمزگشایی را محدود می کند. برای جزئیات بیشتر به پیشنهاد ارائه پیشنهاد API API Attribution مراجعه کنید.

گزارش های قابل جمع API

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

داده های منبع قابل جمع را ثبت کنید

هنگامی که API با پاسخ به یک زمینه جدید به نام aggregation_keys در HTTP Attribution-Reporting-Source ، می تواند لیستی از کلیدهای جمع آوری ، با نام histogram_contributions را ثبت کند ، با key_name Aggregation_Keys در HTTP Attribution-Reporting-Register-Source ثبت کند. و مقدار به عنوان key_piece :

• (کلید) نام کلید: رشته ای برای نام کلید. به عنوان یک کلید پیوست برای ترکیب با کلیدهای سمت ماشه برای تشکیل کلید نهایی استفاده می شود.
• (مقدار) قطعه کلید: یک مقدار بیتستر برای کلید.

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

کلیدهای نهایی به حداکثر 128 بیت محدود می شوند. کلیدهای طولانی تر از این کوتاه شده اند. این بدان معنی است که رشته های هگز در JSON باید حداکثر 32 رقم محدود شوند.

در مورد نحوه ساخت کلیدهای جمع آوری و چگونگی پیکربندی کلیدهای جمع آوری بیشتر بدانید .

در مثال زیر ، یک فناوری تبلیغی از API برای جمع آوری موارد زیر استفاده می کند:

• تبدیل کل در سطح کمپین شمارش می شود
• مقادیر خرید کل در سطح GEO

// This is where the Attribution-Reporting-Register-Source object appears when
// an ad tech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Source:
…
aggregation_keys: {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).

  "campaignCounts": "0x159",
  // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue"
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
  "geoValue": "0x5"
}

ماشه قابل جمع را ثبت کنید

ثبت نام ماشه شامل دو قسمت اضافی است.

قسمت اول برای ثبت لیستی از کلیدهای کل در سمت ماشه استفاده می شود. فناوری تبلیغی باید با قسمت aggregatable_trigger_data در HTTP Attribution-Reporting-Register-Trigger پاسخ دهد ، با زمینه های زیر برای هر کلید کل در لیست:

• قطعه کلیدی: یک مقدار بیتستر برای کلید.
• کلیدهای منبع: لیستی از رشته ها با نام کلیدهای جانبی منبع Attribution که باید کلید ماشه با آن ترکیب شود تا کلیدهای نهایی را تشکیل دهد.

قسمت دوم برای ثبت لیستی از مقادیر استفاده می شود که باید به هر کلید کمک کند. فناوری AD باید با قسمت aggregatable_values ​​در HTTP Attribution-Reporting-Register-Trigger پاسخ دهد. قسمت دوم برای ثبت لیستی از مقادیر استفاده می شود که باید به هر کلید کمک کند ، که می تواند عدد صحیح در محدوده $ [1 ، 2^{16}] $ باشد.

هر ماشه می تواند چندین سهم در گزارش های قابل جمع شدن داشته باشد. مقدار کل مشارکت در هر رویداد منبع معین توسط یک پارامتر L1 $ $ محدود می شود ، که حداکثر مجموع سهم (مقادیر) در تمام کلیدهای کل برای یک منبع معین است. $ L1 $ به حساسیت L1 یا هنجار کمک های هیستوگرام در هر رویداد منبع اشاره دارد. فراتر از این محدودیت ها باعث می شود کمک های آینده به سکوت بیفتد. پیشنهاد اولیه تنظیم L1 $ $ 2 $ {16} $ (65536) است.

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

در مثال زیر ، بودجه حریم خصوصی با تقسیم سهم L1 $ $ در هر یک به طور مساوی بین campaignCounts و geoValue تقسیم می شود:

// This is where the Attribution-Reporting-Register-Trigger object appears
// when an ad tech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Trigger:{
    …
    "aggregatable_trigger_data":

    [
    // Each dictionary independently adds pieces to multiple source keys.
    {
    // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
    // A 9-bit offset is needed because there are 511 possible campaigns, which
    // will take up 9 bits in the resulting key.
        "key_piece": "0x400",// Conversion type purchase = 2
        // Apply this key piece to:
        "source_keys": ["campaignCounts"]
    },
    {
    // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
    // A 7-bit offset is needed because there are ~100 regions for the geo key,
    // which will take up 7 bits of space in the resulting key.
        "key_piece": "0xA80",
        // Apply this key piece to:
        "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
    }
    ]

    // Specify an amount of an abstract value which can be integers in [1, 2^16] to
    // contribute to each key that is attached to aggregation keys in the order that
    // they're generated.
    aggregatable_values:
    {
    // Privacy budget for each key is L1 / 2 = 2^15 (32768).
    // Conversion count was 1.
    // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
        "campaignCounts": 32768,

    // Purchase price was $52.
    // Purchase values for the app range from $1 to $1,024 (integers only).
    // Scaling factor applied is 32768 / 1024 = 32.
    // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
        "geoValue": 1664
    }
}

مثال قبلی سهم هیستوگرام زیر را ایجاد می کند:

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

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

برای به دست آوردن مقادیر صحیح ، سر و صدای ماژول که اعمال می شود ، می توان فاکتورهای مقیاس گذاری را معکوس کرد:

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

حریم خصوصی متفاوت

هدف از این API داشتن چارچوبی است که می تواند از اندازه گیری کل خصوصی متفاوت پشتیبانی کند. این می تواند با افزودن سر و صدای متناسب با بودجه L1 $ ، مانند انتخاب نویز با توزیع زیر حاصل شود:

\[ Laplace(\frac{L1}{ε}) \]

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

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

از طریق این ادغام متقابل API ، AdTechs می تواند:

• یک نقشه با ارزش کلیدی از URIS ایجاد کنید تا برای هر دو) گزارش تعامل و 2) ثبت منبع استفاده شود.
• شامل CustomAudience در نقشه برداری کلید سمت منبع خود برای گزارش خلاصه کل (با استفاده از API گزارش انتساب).

وقتی کاربر روی یک تبلیغ می بیند یا کلیک می کند:

• URL مورد استفاده برای گزارش آن تعامل با استفاده از مخاطبان محافظت شده نیز برای ثبت یک نمای یا کلیک به عنوان منبع واجد شرایط با API گزارش انتساب استفاده می شود.
• AD Tech ممکن است با استفاده از آن URL ، تصویب CustomAudience (یا سایر اطلاعات متنی مربوطه در مورد تبلیغ مانند قرار دادن تبلیغ یا مدت زمان مشاهده) را انتخاب کند تا این ابرداده بتواند هنگام بررسی عملکرد کمپین ، به گزارش های خلاصه انتشار دهد.

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

اولویت ، انتساب و نمونه های گزارش ثبت نام

این مثال مجموعه ای از تعامل کاربر را به نمایش می گذارد و اینکه چگونه منبع انتسابی تعریف شده و اولویت های تحریک شده می تواند بر گزارش های انتساب تأثیر بگذارد. در این مثال موارد زیر را فرض می کنیم:

• تمام منابع و محرک های انتساب برای همان تبلیغ کننده توسط همان فناوری تبلیغاتی ثبت شده اند.
• تمام منابع و محرک های انتساب در اولین پنجره گزارش رویداد (در طی 2 روز از نمایش در ابتدا تبلیغات در یک برنامه ناشر) اتفاق می افتد.

موردی را در نظر بگیرید که کاربر موارد زیر را انجام دهد:

1. کاربر یک تبلیغ را می بیند. AD Tech یک منبع انتساب با API ، با اولویت 0 (مشاهده شماره 1) ثبت می کند.
2. کاربر یک تبلیغ را می بیند ، که با اولویت 0 ثبت شده است (مشاهده شماره 2).
3. کاربر روی یک تبلیغ کلیک می کند ، با اولویت 1 ثبت شده است (روی شماره 1 کلیک کنید).
4. کاربر در یک برنامه تبلیغاتی (به صفحه فرود می رسد) تبدیل می کند. AD Tech با اولویت 0 (تبدیل شماره 1) یک ماشه را با API ثبت می کند.
   • با ثبت محرک ها ، API ابتدا قبل از تولید گزارش ، انتساب را انجام می دهد.
   • 3 منبع انتساب در دسترس است: مشاهده شماره 1 ، مشاهده شماره 2 ، و روی شماره 1 کلیک کنید. API این ماشه را برای کلیک روی شماره 1 نسبت می دهد زیرا این بالاترین اولویت و جدیدترین است.
   • مشاهده شماره 1 و مشاهده شماره 2 دور ریخته شده و دیگر واجد شرایط انتساب آینده نیستند.
5. کاربر در برنامه تبلیغات ، یک مورد را به سبد خرید خود اضافه می کند ، با اولویت 1 (تبدیل شماره 2) ثبت شده است.
   • کلیک شماره 1 تنها منبع واجد شرایط واجد شرایط است. API این ماشه را برای کلیک روی شماره 1 ویژگی می کند.
6. کاربر در برنامه تبلیغاتی ، موردی را به سبد خرید خود اضافه می کند ، که با اولویت 1 (تبدیل شماره 3) ثبت شده است.
   • کلیک شماره 1 تنها منبع واجد شرایط واجد شرایط است. API این ماشه را برای کلیک روی شماره 1 ویژگی می کند.
7. کاربر در برنامه تبلیغات ، یک مورد را به سبد خرید خود اضافه می کند ، با اولویت 1 (تبدیل شماره 4) ثبت شده است.
   • کلیک شماره 1 تنها منبع واجد شرایط واجد شرایط است. API این ماشه را برای کلیک روی شماره 1 ویژگی می کند.
8. کاربر در برنامه تبلیغاتی که با اولویت 2 (تبدیل شماره 5) ثبت شده است ، خرید می کند.
   • کلیک شماره 1 تنها منبع واجد شرایط واجد شرایط است. API این ماشه را برای کلیک روی شماره 1 ویژگی می کند.

گزارش های سطح رویداد ویژگی های زیر را دارند:

• به طور پیش فرض ، 3 محرک اول منتسب به یک کلیک و اولین ماشه منتسب به یک نمای پس از ویندوزهای گزارشگر قابل استفاده ارسال می شوند.
• در پنجره گزارش ، اگر محرک هایی با اولویت بالاتر ثبت شوند ، این موارد مقدم هستند و جدیدترین ماشه را جایگزین می کنند.
• در مثال قبلی ، AD Tech 3 گزارش رویداد را پس از پنجره گزارش 2 روزه ، برای تبدیل شماره 2 ، تبدیل شماره 3 و تبدیل شماره 5 دریافت می کند.
  • تمام 5 محرک به کلیک شماره 1 نسبت داده می شوند. به طور پیش فرض ، API گزارش هایی را برای 3 محرک اول ارسال می کند: تبدیل شماره 1 ، تبدیل شماره 2 و تبدیل شماره 3.
  • با این حال ، اولویت تبدیل شماره 4 ( 1 ) بالاتر از اولویت تبدیل شماره 1 ( 0 ) است. گزارش رویداد شماره 4 جایگزین گزارش رویداد تبدیل شماره 1 برای ارسال شده است.
  • علاوه بر این ، اولویت تبدیل شماره 5 ( 2 ) از هر محرک دیگری بالاتر است. گزارش رویداد شماره 5 جایگزین گزارش تبدیل شماره 4 برای ارسال شده است.

گزارش های قابل جمع ویژگی های زیر را دارند:

• گزارش های قابل استفاده رمزگذاری شده به محض پردازش ، چند ساعت پس از ثبت نام ، به فناوری تبلیغاتی ارسال می شوند.

  به عنوان یک فناوری تبلیغاتی ، شما دسته های آنها را بر اساس اطلاعاتی که در گزارش های قابل قبول شما رمزگذاری نشده است ، ایجاد می کنید. این اطلاعات در گزارش مشترک شما در قسمت shared_info موجود است و شامل زمان بندی و منشأ گزارش است. شما نمی توانید بر اساس هرگونه اطلاعات رمزگذاری شده در جفت های ارزش کلیدی خود ، دسته ای را دسته بندی کنید. برخی از استراتژی های ساده ای که می توانید دنبال کنید گزارش های روزانه یا هفتگی است. در حالت ایده آل ، دسته ها باید حداقل 100 گزارش داشته باشند.

• این به فناوری تبلیغاتی در مورد زمان و چگونگی دسته بندی گزارش های قابل جمع شدن و ارسال به سرویس جمع آوری بستگی دارد.

• در مقایسه با گزارش های سطح رویداد ، گزارش های قابل استفاده رمزگذاری شده می توانند محرک های بیشتری را به یک منبع نسبت دهند.

• در مثال قبلی ، 5 گزارش قابل جمع شدن ارسال می شود ، یکی برای هر ماشه ثبت شده.

گزارش های اشکال زدایی انتقالی

API گزارش دهنده انتساب روشی جدید و نسبتاً پیچیده برای انجام اندازه گیری انتساب بدون شناسه های متقاطع است. به همین ترتیب ، ما از یک مکانیسم انتقالی برای کسب اطلاعات بیشتر در مورد گزارش های انتساب در هنگام موجود بودن شناسه تبلیغاتی پشتیبانی می کنیم (کاربر با استفاده از شناسه تبلیغاتی از شخصی سازی خودداری نکرده است و ناشر یا برنامه تبلیغ کننده مجوزهای ADID را اعلام کرده است) . این امر تضمین می کند که API را می توان به طور کامل در حین بازپرداخت درک کرد ، به بیرون کشیدن هرگونه اشکال کمک کرد و راحت تر عملکرد را با گزینه های مبتنی بر شناسه تبلیغاتی مقایسه کرد. دو نوع گزارش اشکال زدایی وجود دارد: انتساب-موفقیت و کلامی.

برای جزئیات بیشتر در مورد گزارش های اشکال زدایی با اندازه گیری برنامه به WEB و وب به برنامه ، راهنمای گزارش های اشکال زدایی انتقالی را بخوانید.

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

ثبت نام های منبع و ماشه هر دو یک قسمت جدید 64 بیتی debug_key (فرمت به عنوان یک رشته) را می پذیرند ، که فناوری تبلیغی جمع می شود. source_debug_key و trigger_debug_key در گزارش های سطح رویداد و کل بدون تغییر منتقل می شوند.

If a report is created with both source and trigger debug keys, a duplicate debug report is sent with limited delay to a .well-known/attribution-reporting/debug/report-event-attribution endpoint. The debug reports are identical to normal reports, including both debug key fields. Including these keys in both allows tying normal reports to the separate stream of debug reports.

• For event-level reports:
  • Duplicate debug reports are sent with limited delay and therefore aren't suppressed by limits on available triggers , which allows ad tech to understand the impact of those limits for event-level reports.
  • Event-level reports associated with false trigger events will not have trigger_debug_key s. This allows ad tech to more closely understand how noise is applied in the API.
• For aggregatable reports:
  • We will support a new debug_cleartext_payload field which contains the decrypted payload, only if both source_debug_key and trigger_debug_key are set.

Verbose debugging reports

Verbose debugging reports allow developers to monitor certain failures in the attribution source or trigger registrations. These debugging reports are sent with limited delay after attribution source or trigger registrations to a . well-known/attribution-reporting/debug/verbose endpoint.

Each verbose report contains the following fields:

• Type : what caused the report to be generated. See the full list of verbose report types .
  • In general, there are source verbose reports and trigger verbose reports.
  • Source verbose reports require the advertising ID to be available to the publisher app, and trigger verbose reports require the advertising ID to be available to the advertiser app.
  • Trigger verbose reports (with the exception of trigger-no-matching-source ) can optionally include the source_debug_key . This can only be included if the advertising ID is also available to the publisher app.
• Body : The report's body, which depends on its type.

Ad techs need to opt in to receive verbose debugging reports using a new debug_reporting dictionary field in the Attribution-Reporting-Register_Source and Attribution-Reporting-Register-Trigger headers.

• Source verbose reports require opt-in on the source registration header only.
• Trigger debug reports require opt-in on the trigger registration header only.

How to use debug reports

If a conversion took place (according to your existing measurement system) and a debug report was received for that conversion, this means the trigger was successfully registered.

For each debug attribution report, check if you're receiving a regular attribution report that matches the two debug keys.

When there's no match, it can be for a number of reasons.

Works as intended:

• Privacy-preserving API behaviors:
  • A user hits the report rate limit—causing all subsequent reports to not be sent in the time period; or a source is removed due to the pending destination limit.
  • For event-level reports: the report is subject to randomized response (noise) and is suppressed, or you may receive a randomized report.
  • For event-level reports: the limit of three (for clicks) or one (for views) reports has been reached, and subsequent reports have no explicit priority set, or a priority that is lower than existing reports.
  • The contribution limits for aggregatable reports have been exceeded.
• Ad tech-defined business logic:
  • A trigger is filtered out via filters or priority rules.
• Time delays or interactions with network availability (eg, the user turns off their device for an extended period of time).

Unintended causes:

• Implementation issues:
  • The source header is misconfigured.
  • The trigger header is misconfigured.
  • Other configuration issues.
• Device or network issues:
  • Failures due to network conditions.
  • Source or trigger registration response doesn't reach the client.
  • API bug.

Future considerations & open questions

The Attribution Reporting API is a work in progress. We're also exploring future potential features, such as non-last-click attribution models and cross-device measurement use cases.

Additionally, we'd like to seek feedback from the community on a few issues:

1. Are there any use cases where you'd like the API to send out reports for the verified install? These reports would count against ad tech platforms' respective rate limits.
2. Do you foresee any difficulties with passing the InputEvent from the app to ad tech for source registration?
3. Do you have any special attribution use cases for pre-loaded apps or re-installed apps?

،

Note: This document reflects the Privacy Sandbox on Android's current design proposals and is subject to further change. We encourage your feedback and comments to assist in these efforts.

به روز رسانی های اخیر

• Updated the list of upcoming changes and known issues

• Introduced lite flexible event-level configuration, as a bridge to the full flexible event-level configuration

• Starting in September 2023, registerWebSource , registerWebTrigger , registerAppSource and registerAppTrigger must use strings for fields that expect a numeric value (such as priority , source_event_id , debug_key , trigger_data , deduplication_key , etc.)

• In Q4 2023, Google Cloud support in the Android Attribution Reporting API will be added to generate summary reports using Aggregation Service on Google Cloud, more specific timing reflected here. See the deployment guide for more information on setting up Aggregation Service with Google Cloud.

• New privacy preserving rate limits for number of unique destinations.

• Updated functionality for lookback window trigger filters will be coming in Q1 2024, see the note for further information.

نمای کلی

Today, it's common for mobile attribution and measurement solutions to use cross-party identifiers, such as Advertising ID. The Attribution Reporting API is designed to provide improved user privacy by removing reliance on cross-party user identifiers, and to support key use cases for attribution and conversion measurement across apps and the web.

This API has the following structural mechanisms that offer a framework for improving privacy, which later sections on this page describe in more detail:

• Limits the number of bits available for event-level reports

• Enables higher-fidelity conversion data only in aggregatable reports

• Introduces rate limits for available triggers (conversions) and the number of ad techs that can be associated with a single attribution source

• Incorporates various noise adding techniques

The preceding mechanisms limit the ability to link user identity across two different apps or domains.

The Attribution Reporting API supports the following use cases:

• Conversion reporting: Help advertisers measure the performance of their campaigns by showing them conversion (trigger) counts and conversion (trigger) values across various dimensions, such as by campaign, ad group, and ad creative.
• Optimization: Provide event-level reports that support optimization of ad spend, by providing per-impression attribution data that can be used to train ML models.
• Invalid activity detection: Provide reports that can be used in invalid traffic and ad fraud detection and analysis.

At a high level, the Attribution Reporting API works as follows, which later sections of this document describe in more detail:

1. The ad tech completes an enrollment process to use the Attribution Reporting API.
2. The ad tech registers attribution sources —ad clicks or views—with the Attribution Reporting API.
3. The ad tech registers triggers —user conversions on the advertiser app or website—with the Attribution Reporting API.
4. The Attribution Reporting API matches triggers to attribution sources—a conversion attribution—and one or more triggers are sent off-device through event-level and aggregatable reports to ad techs.

Note: For more information about how to implement this design for an app-to-app attribution use case, read the cross-network attribution section of the Attribution Reporting API Developer's Guide. To learn how to implement an app-to-web or web-to-app use case, read the cross app and web measurement design proposal .

Get access to Attribution Reporting APIs

Ad tech platforms need to enroll to access the Attribution Reporting APIs, see Enroll for a Privacy Sandbox account for more information.

Register an attribution source (click or view)

The Attribution Reporting API refers to ad clicks and views as attribution sources . To register an ad click or ad view, call registerSource() . This API expects the following parameters:

• Attribution source URI: The platform issues a request to this URI in order to fetch metadata associated with the attribution source.
• Input event: Either an InputEvent object (for a click event) or null (for a view event).

When the API makes a request to the Attribution Source URI, the ad tech should respond with the attribution source metadata in a new HTTP header Attribution-Reporting-Register-Source , with the following fields:

• Source event ID : This value represents the event-level data associated with this attribution source (ad click or view). Must be a 64-bit unsigned integer formatted as a string.
• Destination : An origin whose eTLD+1 or app package name where the trigger event happens.
• Expiry (optional) : Expiry, in seconds, for when the source should be deleted off the device. Default is 30 days, with a minimum value of 1 day and a maximum value of 30 days. This is rounded to the nearest day. Can be formatted as either a 64-bit unsigned integer or string.
• Event report window (optional) : Duration in seconds after source registration during which event reports may be created for this source. If the event report window has passed, but the expiry has not yet passed, a trigger can still be matched with a source, but an event report is not sent for that trigger. Cannot be greater than Expiry. Can be formatted as either a 64-bit unsigned integer or string.
• Aggregatable report window (optional) : Duration in seconds after source registration during which aggregatable reports may be created for this source. Cannot be greater than Expiry. Can be formatted as either a 64-bit unsigned integer or string.
• Source priority (optional) : Used to select which attribution source a given trigger should be associated with, in case multiple attribution sources could be associated with the trigger. Must be a 64-bit signed integer formatted as a string.
  
  When a trigger is received, the API finds the matching attribution source with the highest source priority value and generates a report. Each ad tech platform can define its own prioritization strategy. For more details on how priority impacts attribution, see the prioritization example section.
  
  Higher values indicate higher priorities.
• Install and post-install attribution windows (optional): Used to determine attribution for post-install events , described later on this page.
• Filter data (optional): Used to selectively filter some triggers, effectively ignoring them. For more details, see the trigger filters section on this page.
• Aggregation keys (optional): Specify segmentation to be used for aggregatable reports .

Optionally, the attribution source metadata response may include additional data in the Attribution reporting redirects header. The data contains redirect URLs, which allow multiple ad techs to register a request .

The developer guide includes examples that show how to accept source registration .

The following steps show an example workflow:

1. The ad tech SDK calls the API to initiate attribution source registration, specifying a URI for the API to call:

   registerSource(
       Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
       myClickEvent);
   

2. The API makes a request to https://adtech.example/attribution_source? AD_TECH_PROVIDED_METADATA , using one of the following headers:

   <!-- For click events -->
   Attribution-Reporting-Source-Info: navigation
   
   <!-- For view events -->
   Attribution-Reporting-Source-Info: event
   

3. This ad tech's HTTPS server replies with headers containing the following:

   Attribution-Reporting-Register-Source: {
       "destination": "android-app://com.advertiser.example",
       "source_event_id": "234",
       "expiry": "60000",
       "priority": "5"
   }
   Attribution-Reporting-Redirect:
   https://adtechpartner1.example?their_ad_click_id=567
   Attribution-Reporting-Redirect:
   https://adtechpartner2.example?their_ad_click_id=890
   

4. The API makes a request to each URL specified in Attribution-Reporting-Redirect . In this example, two ad tech partner URLs are specified, so the API makes one request to https://adtechpartner1.example?their_ad_click_id=567 and another request to https://adtechpartner2.example?their_ad_click_id=890 .

5. This ad tech's HTTPS server replies with headers containing the following:

   Attribution-Reporting-Register-Source: {
       "destination": "android-app://com.advertiser.example",
       "source_event_id": "789",
       "expiry": "120000",
       "priority": "2"
   }
   

   Note: ad techs' replies can specify different metadata in the Attribution-Reporting-Register-Source header.

Three navigation (click) attribution sources are registered based on the requests shown in the previous steps.

Register an attribution source from WebView

WebView supports the use case where an app is rendering an ad within a WebView. This is handled by WebView directly calling registerSource() as a background request. This call associates the attribution source to the app instead of the top-level origin. Registering sources from embedded web content within a browser context is also supported; both API callers and apps need to adjust settings to do so. See Register attribution source and trigger from WebView for instructions for API callers and Attribution source and trigger registration from WebView for instructions for apps.

Since ad techs use common code across Web and WebView, WebView follows HTTP 302 redirects and passes on the valid registrations to the platform. We don't plan to support the Attribution-Reporting-Redirect header for this scenario, but reach out if you have an impacted use case.

Note: To allow WebViews to use the Attribution Reporting API, the embedding app needs to be configured with the correct permissions .

Register a trigger (conversion)

Ad tech platforms can register triggers —conversions such as installs or post-install events—using the registerTrigger() method.

The registerTrigger() method expects the Trigger URI parameter. The API issues a request to this URI to fetch metadata associated with the trigger.

The API follows redirects. The ad tech server response should include an HTTP header called Attribution-Reporting-Register-Trigger , which represents information on one or more registered triggers. The header's content should be JSON-encoded and include the following fields:

• Trigger data: Data to identify the trigger event (3 bits for clicks, 1 bit for views). Must be a 64-bit signed integer formatted as a string.

• Trigger priority (optional): Represents the priority of this trigger compared to other triggers for the same attribution source. Must be a 64-bit signed integer formatted as a string. For more details on how priority impacts reporting, see the prioritization section section.

• Deduplication key (optional): Used to identify cases where the same trigger is registered multiple times by the same ad tech platform, for the same attribution source. Must be a 64-bit signed integer formatted as a string.

• Aggregation keys (optional): A list of dictionaries which specifies aggregation keys and which aggregatable reports should have their value aggregated.

• Aggregation values (optional): A list of amounts of value which contribute to each key.

• Filters (optional): Used to selectively filter triggers or trigger data. For more details, see the trigger filters section on this page.

Optionally, the ad tech server response may include additional data in the Attribution Reporting Redirects header. The data contains redirect URLs, which allow multiple ad techs to register a request .

Multiple ad techs can register the same trigger event using either redirects in the Attribution-Reporting-Redirect field or multiple calls to the registerTrigger() method. We recommend that you use the deduplication key field to avoid including duplicate triggers in reports in the case that the same ad tech provides multiple responses for the same trigger event. Learn more about how and when to use a deduplication key .

The Developer's Guide includes examples that show how to accept trigger registration .

The following steps show an example workflow:

1. The Ad tech SDK calls the API to initiate trigger registration using a pre-enrolled URI. See Enroll for a Privacy Sandbox account for more information.

   registerTrigger(
       Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
   

2. The API makes a request to https://adtech.example/attribution_trigger? AD_TECH_PROVIDED_METADATA .

3. This ad tech's HTTPS server replies with headers containing the following:

   Attribution-Reporting-Register-Trigger: {
       "event_trigger_data": [{
       "trigger_data": "1122",
       // This returns 010 for click-through conversions (CTCs) and 0 for
       // view-through conversions (VTCs) in reports
       "priority": "3",
       "deduplication_key": "3344"
       }],
   }
   Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567
   

   Note: Only the ad tech that initiates the API call can specify partners in Attribution-Reporting-Redirect .

4. The API makes a request to each URL specified in Attribution-Reporting-Redirect . In this example, only one URL is specified, so the API makes a request to https://adtechpartner.example?app_install=567 .

5. This ad tech's HTTPS server replies with headers containing the following:

   Attribution-Reporting-Register-Trigger: {
   "event_trigger_data":[{
     "trigger_data": "5566",
     "priority": "3",
     "deduplication_key": "3344"
   }]
   }
   

   Two triggers are registered based on the requests in the previous steps.

Attribution capabilities

The following sections explain how the Attribution Reporting API matches conversion triggers to attribution sources.

Source-prioritized attribution algorithm applied

The Attribution Reporting API employs a source-prioritized attribution algorithm to match a trigger (conversion) to an attribution source.

Priority parameters provide ways to customize the attribution of triggers to sources:

• You can attribute triggers to certain ad events over others. For example, you may choose to place more emphasis on clicks rather than views, or focus on events from certain campaigns.
• You can configure the attribution source and trigger such that, if you hit rate limits, you're more likely to receive the reports that are more important to you. For example, you might want to make sure that biddable conversions or high-value conversions are more likely to appear in these reports.

In the case where multiple ad techs register an attribution source , as described later on this page, this attribution happens independently for each ad tech. For each ad tech, the attribution source with the highest priority is attributed with the trigger event. If there are multiple attribution sources with the same priority, the API picks the last registered attribution source. Any other attribution sources, that aren't picked are discarded and are no longer eligible for future trigger attribution.

Trigger filters

Source and trigger registration includes additional optional features to do the following:

• Selectively filter some triggers, effectively ignoring them.
• Choose trigger data for event-level reports based on source data.
• Choose to exclude a trigger from event-level reports.

To selectively filter triggers, the ad tech can specify filter data, consisting of keys and values, during source and trigger registration. If the same key is specified for both the source and trigger, then the trigger is ignored if the intersection is empty. For example, a source can specify "product": ["1234"] , where product is the filter key and 1234 is the value. If the trigger filter is set to "product": ["1111"] , then the trigger is ignored. If there is no trigger filter key matching product , then the filters are ignored.

Another scenario where ad tech platforms may want to selectively filter triggers is to force a shorter expiry window. On trigger registration, an ad tech can specify (in seconds) a lookback window from when the conversion happened; for example, a 7 day lookback window would be defined as: "_lookback_window": 604800 // 7d

To decide if a filter matches, the API will first check the lookback window. If available, the duration since the source was registered must be smaller or equal to the lookback window duration.

Note: The lookback filter logic and functionality described will be in effect in Q124. You can find more specific detail on release timing . Previous logic required lookback windows to be specified by the hour, on both the source and trigger side. This updated feature logic is backwards incompatible, meaning sources using the previous "_lookback_window" key won't be successfully registered.

Ad tech platforms can also choose trigger data based on source event data. For example, source_type is automatically generated by the API as either navigation or event . During trigger registration, trigger_data can be set as one value for "source_type": ["navigation"] and as a different value for "source_type": ["event"] .

Triggers are excluded from event-level reports if any of the following are true:

• There is no trigger_data specified.
• Source and trigger specify the same filter key, but the values don't match. Note that, in this case, the trigger is ignored for both event-level and aggregatable reports.

Post-install attribution

In some cases, there is a need for post-install triggers to be attributed to the same attribution source that drove the install, even if there are other eligible attribution sources that occurred more recently.

The API can support this use case by allowing ad techs to set a post-install attribution period:

• When registering an attribution source, specify an install attribution window during which installs are expected (generally 2-7 days, accepted range 1 to 30 days). Specify this time window as a number of seconds.
• When registering an attribution source, specify a post-install attribution exclusivity window where any post-install trigger events should be associated with the attribution source that drove the install (generally 7-30 days, accepted range 0 to 30 days). Specify this time window as a number of seconds.
• The Attribution Reporting API validates when an app install happens and internally attributes the install to the source-prioritized attribution source. However, the install isn't sent to ad techs and doesn't count against the platforms' respective rate limits.
• App install validation is available for any downloaded app.
• Any future triggers that happen within the post-install attribution window are attributed to the same attribution source as the validated install, as long as that attribution source is eligible.

In the future, we might explore extending the design to support more advanced attribution models.

The following table shows an example of how ad techs may use post-install attribution. Assume all attribution sources and triggers are being registered by the same ad tech network, and all priorities are the same.

رویداد	Day when event occurs	یادداشت ها
1 را کلیک کنید	1	install_attribution_window is set to 172800 (2 days), and post_install_exclusivity_window is set to 864000 (10 days)
Verified Install	2	The API internally attributes verified installs, but those installs aren't considered triggers. Therefore, no reports are sent at this point.
Trigger 1 (First Open)	2	First trigger registered by ad tech. In this example, it represents a first open but can be any trigger type. Attributed to click 1 (matches attribution of verified install).
روی 2 کلیک کنید	4	Uses the same values for install_attribution_window and post_install_exclusivity_window as Click 1
Trigger 2 (Post Install)	5	Second trigger registered by ad tech. In this example, it represents a post-install conversion like a purchase. Attributed to click 1 (matches attribution of verified install). Click 2 is discarded and isn't eligible for future attribution.

The following list provides some additional notes regarding post-install attribution:

• If the verified install doesn't happen within the number of days specified by install_attribution_window , post-install attribution isn't applied.
• Verified installs aren't registered by ad techs and aren't sent out in reports. They don't count against an ad tech's rate limits. Verified installs are only used to identify the attribution source that is credited with the install.
• In the example from the preceding table, trigger 1 and trigger 2 represent a first open and a post-install conversion, respectively. However, ad tech platforms can register any type of trigger. In other words, the first trigger need not be a first open trigger.
• If more triggers are registered after the post_install_exclusivity_window expires, click 1 is still eligible for attribution, assuming it hasn't expired and hasn't reached its rate limits.
  • Click 1 may still lose, or be discarded, if a higher-priority attribution source is registered.
• If the advertiser app is uninstalled and reinstalled, the reinstall is counted as a new verified install.
• If click 1 was a view event instead, both the "first open" and post-install triggers are still attributed to it. The API restricts attribution to one trigger per view, except in the case of post-install attribution where up to two triggers per view are allowed. In the post-install attribution case, the ad tech could receive 2 different reporting windows (at 2 days or at source expiry).

All combinations of app- and web-based trigger paths are supported

The Attribution Reporting API enables attribution of the following trigger paths on a single Android device:

• App-to-app: The user sees an ad in an app, then converts in either that app or another installed app.
• App-to-web: The user sees an ad in an app, then converts in a mobile or app browser.
• Web-to-app: The user sees an ad in a mobile or app browser, then converts in an app.
• Web-to-web: The user sees an ad in a mobile or app browser, then converts in either the same browser or another browser on the same device.

We allow web browsers to support new web-exposed features, such as functionality that's similar to the Privacy Sandbox for the Web's Attribution Reporting API , which can call the Android APIs to enable attribution across app and web.

Learn about the changes that ad techs and apps need to make in order to support trigger paths for cross app and web measurement .

Prioritize multiple triggers for a single attribution source

A single attribution source can lead to multiple triggers. For example, a purchase flow could involve an "app install" trigger, one or more "add-to-cart" triggers, and a "purchase" trigger. Each trigger is attributed to one or more attribution sources according to the source-prioritized attribution algorithm , described later on this page.

There are limits on how many triggers can be attributed to a single attribution source . For more details, read the section on viewing measurement data in attribution reports later on this page.

In the cases where there are multiple triggers beyond these limits, it's useful to introduce prioritization logic to get back the most valuable triggers. For example, the developers of an ad tech might want to prioritize getting "purchase" triggers over "add-to-cart" triggers.

To support this logic, a separate priority field can be set on the trigger, and the highest priority triggers are picked before limits are applied, within a given reporting window.

Note: Lower-priority triggers which have already been reported always consume the budget.

Allow multiple ad techs to register attribution sources or triggers

It's common for more than one ad tech to receive attribution reports, generally to perform cross-network deduplication. Therefore, the API allows multiple ad techs to register the same attribution source or trigger. An ad tech must register both attribution sources and triggers to receive postbacks from the API, and attribution is done among the attribution sources and triggers that the ad tech has registered with the API.

Advertisers that want to use a third party to perform cross-network deduplication can continue doing so, using a technique similar to the following:

• Setting up an in-house server to register and receive reports from the API.
• Continuing to use an existing mobile measurement partner.

Attribution sources

Attribution source redirects are supported in the registerSource() method:

1. The ad tech that calls the registerSource() method can provide an additional Attribution-Reporting-Redirect field in their response, which represents the set of partner ad tech's redirect URLs.
2. The API then calls the redirect URLs so the attribution source can be registered by the partner ad techs.

Multiple partner ad tech URLs can be listed in the Attribution-Reporting-Redirect field, and partner ad techs cannot specify their own Attribution-Reporting-Redirect field.

The API also allows different ad techs to each call registerSource() .

محرک ها

For trigger registration, third parties are supported in a similar way: ad techs can either use the additional Attribution-Reporting-Redirect field, or they can each call the registerTrigger() method.

When an advertiser uses multiple ad techs to register the same trigger event, a deduplication key should be used. The deduplication key serves to disambiguate these repeated reports of the same event registered by the same ad tech platform. For example, an ad tech could have their SDK call the API directly to register a trigger and have their URL in the redirect field of another ad tech's call. If no deduplication key is provided, duplicate triggers may be reported back to each ad tech as unique.

Handle duplicate triggers

An ad tech may register the same trigger multiple times with the API. Scenarios include the following:

• The user performs the same action (trigger) multiple times. For example, the user browses the same product multiple times in the same reporting window.
• The advertiser app uses multiple SDKs for conversion measurement, which all redirect to the same ad tech. For example, the advertiser app uses two measurement partners, MMP #1 and MMP #2. Both MMPs redirect to ad tech #3. When a trigger happens, both MMPs register that trigger with the Attribution Reporting API. Ad tech #3 then receives two separate redirects—one from MMP #1 and one from MMP #2—for the same trigger.

In these cases, there are several ways to suppress event-level reports on duplicate triggers, to make it less likely to exceed the rate limits applied to event-level reports . The recommended way is to use a deduplication key.

Recommended method: deduplication key

The recommended method is for the advertiser app to pass a unique deduplication key to any ad techs or SDKs that it's using for conversion measurement. When a conversion happens, the app passes a deduplication key to the ad techs or SDKs. Those ad techs or SDKs then continue passing the deduplication key to redirects using a parameter in the URLs specified in Attribution-Reporting-Redirect .

Ad techs can choose to register only the first trigger with a given deduplication key, or can choose to register multiple triggers or all triggers. Ad techs can specify the deduplication_key when registering duplicate triggers.

If an ad tech registers multiple triggers with the same deduplication key and attributed source, only the first registered trigger is sent in the event-level reports. Duplicate triggers are still sent in encrypted aggregatable reports.

Alternate method: ad techs agree on per-advertiser trigger types

In situations where ad techs do not wish to use the deduplication key, or where the advertiser app cannot pass a deduplication key, an alternate option exists. All ad techs measuring conversions for a given advertiser need to work together to define different trigger types for each advertiser.

Ad techs that initiate the trigger registration call—for example, SDKs—include a parameter in URLs specified in Attribution-Reporting-Redirect , such as duplicate_trigger_id . That duplicate_trigger_id parameter can include information like the SDK name and the trigger type for that advertiser. Ad techs can then send a subset of these duplicate triggers to event-level reports. Ad techs can also include this duplicate_trigger_id in their aggregation keys.

Cross-network attribution example

In the example described in this section, the advertiser is using two serving ad tech platforms (Ad tech A and Ad tech B) and one measurement partner (MMP).

To start, Ad tech A, Ad tech B, and MMP must each complete enrollment to use the Attribution Reporting API. See Enroll for a Privacy Sandbox account for more information.

The following list provides a hypothetical series of user actions that each occur one day apart, and how the Attribution Reporting API handles those actions with respect to Ad tech A, Ad tech B, and MMP:

Day 1: User clicks on an ad served by Ad tech A

Ad tech A calls registerSource() with their URI. The API makes a request to the URI, and the click is registered with the metadata from Ad tech A's server response.

Ad tech A also includes MMP's URI in the Attribution-Reporting-Redirect header. The API makes a request to MMP's URI, and the click is registered with the metadata from MMP's server response.

Day 2: User clicks on an ad served by Ad tech B

Ad tech B calls registerSource() with their URI. The API makes a request to the URI, and the click is registered with the metadata from Ad tech B's server response.

Like Ad tech A, Ad tech B has also included MMP's URI in the Attribution-Reporting-Redirect header. The API makes a request to MMP's URI, and the click is registered with the metadata from the MMP's server response.

Day 3: User views an ad served by Ad tech A

The API responds in the same way that it did on Day 1, except that a view is registered for Ad tech A and MMP.

Day 4: User installs the app, which uses the MMP for conversion measurement

MMP calls registerTrigger() with their URI. The API makes a request to the URL, and the conversion is registered with the metadata from MMP's server response.

MMP also includes the URIs for Ad tech A and Ad tech B in the Attribution-Reporting-Redirect header. The API makes requests to Ad tech A and Ad tech B's servers, and the conversion is registered accordingly with the metadata from the server responses.

The following diagram illustrates the process described in the preceding list:

Example of how the Attribution Reporting API responds to a series of user actions.

Attribution works as follows:

• Ad tech A sets the priority of clicks higher than views and therefore gets the install attributed to the click on Day 1.
• Ad tech B gets the install attributed on Day 2.
• MMP sets the priority of clicks higher than views and gets the install attributed to the click on Day 2. Day 2's click is the highest priority, most recent ad event.

Cross-network attribution without redirects

While we recommend utilizing redirects to allow multiple ad techs to register attribution sources and triggers, we recognize that there may be scenarios where using redirects isn't feasible. This section will detail how to support cross-network attribution without redirects.

جریان سطح بالا

1. On source registration, the serving ad tech network shares their source aggregation keys.
2. On trigger registration, the advertiser or measurement partner chooses which source-side key pieces to use and specifies their attribution configuration.
3. Attribution is based on the attribution config, shared keys, and any sources that were actually registered by that advertiser or measurement partner (eg from another serving ad tech network that has enabled redirects).
4. If the trigger is attributed to a source from a non-redirecting serving ad tech, the advertiser or measurement partner can receive an aggregatable report that combines the source and trigger key pieces defined in step #2.

Source registration

On source registration, the serving ad tech network can choose to share their source aggregation keys or a subset of their source aggregation keys instead of redirecting. The serving ad tech is not required to actually use these source keys in their own aggregatable reports and can declare them only on behalf of the advertiser or measurement partner if needed.

Shared aggregation keys are available to any ad tech that registers a trigger for the same advertiser. However, it is up to the serving ad tech and the trigger measurement ad tech to collaborate on what types of aggregation keys are needed, their names, and how to decode the keys into readable dimensions.

Trigger registration

On trigger registration, the measurement ad tech chooses which source-side key pieces to apply to each trigger key piece, including any shared by serving ad techs.

Additionally, the measurement ad tech must also specify their waterfall attribution logic using a new attribution configuration API call. In this config, the ad tech can specify source priority, expiry, and filters for sources that they had no visibility into (for example, sources that did not use a redirect).

انتساب

The Attribution Reporting API performs source-prioritized, last-touch attribution for the measurement ad tech based on their attribution config, shared keys, and any sources they registered. به عنوان مثال:

• The user clicked on ads served by ad techs A, B, C, and D. The user then installed the advertiser's app, which uses a measurement ad tech partner (MMP).
• Ad tech A redirects its sources to the MMP.
• Ad techs B and C do not redirect, but share their aggregation keys.
• Ad tech D neither redirects nor shares aggregation keys.

The MMP registers a source from Ad tech A, and defines an attribution config that includes Ad tech B and Ad tech D.

Attribution for the MMP now includes:

• Ad tech A, since the MMP registered a source from that ad tech's redirect.
• Ad tech B, since Ad tech B shared keys and the MMP included it in their attribution config.

Attribution for the MMP does not include:

• Ad tech C, since the MMP did not include it in their attribution config.
• Ad tech D, since they did not redirect nor share aggregation keys.

Note: For more information about how to implement this design, read the Attribution Reporting API Developer's Guide .

اشکال زدایی

To support debugging for cross-network attribution without redirects, an additional field, shared_debug_key , is available for ad techs to set upon source registration. If set on the original source registration, it will also be set on the corresponding derived source as debug_key during trigger registration for cross-network attribution without redirects. This debug key is attached as source_debug_key in event and aggregate reports.

This debug feature will only be supported for cross-network attribution without redirects under the following scenarios:

• App to app measurement where AdId is permitted
• App to web measurement where AdId is permitted and matching across both the app source and the web trigger
• Web to web measurement (on the same browser app) when ar_debug ` is present on both source and trigger

Key discovery for cross-network attribution without redirects

Key discovery is intended to streamline how ad techs (usually MMPs) implement their attribution config for the purposes of cross-network attribution when one or several serving ad techs are using shared aggregation keys (as described in Cross-network attribution without redirects above).

When an MMP queries the Aggregation Service to generate summary reports for campaigns that include derived sources, Aggregation Service requires the MMP to specify the list of possible keys as input for the aggregation job. In some cases, the list of potential source aggregation keys may be very large, or unknown. Large lists of possible keys are challenging to track, and are also likely to be quite complex and costly to process. به مثال های زیر توجه کنید:

• List of all possible keys is large:
  • A serving ad network is executing a complex user acquisition initiative that includes 20 campaigns, each with 10 ad groups, and each ad group with 5 creatives that are refreshed every week based on performance.
• List of all possible keys is unknown:
  • A serving ad network is serving ads across many mobile apps where the full list of publisher app IDs is not known at campaign launch.
  • An advertiser is working across multiple serving ad networks that are not redirecting to the MMP on source registration; each serving ad network has a different key structure and values, which may not be shared in advance with the MMP.

With the introduction of key discovery:

• The Aggregation Service no longer requires a full enumeration of possible aggregation keys.
• Instead of having to specify the full list of possible keys, an MMP can create an empty (or partially empty) set of keys and set a threshold, so that only (non pre-declared) keys with values exceeding the threshold are included in the خروجی
• MMP receives a summary report that includes noisy values for keys that have contributing values above the set threshold. The report may also include keys that have no associated real user contributions and are purely noised.
• MMP uses the x_network_bit_mapping field in trigger registration to determine which ad tech corresponds to which key.
• MMP can then contact the appropriate serving ad tech to understand the values in the source key.

In summary, key discovery enables MMPs to obtain aggregation keys without knowing them in advance, and avoid processing a large volume of source keys at the expense of added noise.

Note: This feature is in the proposal stage, and not yet available for testing. Your feedback and comments are encouraged .

Daisy chain redirects

By providing multiple Attribution-Reporting-Redirect headers in a source or trigger registration HTTPS server-response, an ad tech can use the Attribution Reporting API to perform multiple source and trigger registrations with a single registration API call.

In the server-response, the ad tech can also include a single Location (302 redirect) header with a URL, which in turn leads to another registration, up to a set limit.

Both types of headers are optional and none can be provided if redirects are not needed. Either one or both types of headers may be provided. Source and trigger registration requests (including redirects) are retried in case of network failure. The number of retries per request is limited to a fixed number to avoid significant impact on the device.

Redirects are not accepted for registerWebSource and registerWebTrigger used by browsers. More details can be found in the Cross Web and App Implementation Guide .

View measurement data in attribution reports

The Attribution Reporting API enables the following types of reports, described in more detail later on this page:

• Event-level reports associate a particular attribution source (click or view) with limited bits of high-fidelity trigger data.
• Aggregatable reports aren't necessarily tied with a specific attribution source. These reports provide richer, higher-fidelity trigger data than event-level reports, but this data is only available in an aggregate form.

These two report types are complementary to each other and can be used simultaneously.

Event-level reports

After a trigger is attributed to an attribution source, an event-level report is generated and stored on the device until it can be sent back to each ad tech's postback URL during one of the time windows for sending reports , described in more detail later on این صفحه

Event-level reports are useful when very little information is needed about the trigger. Event-level trigger data is limited to 3 bits of trigger data for clicks—which means that a trigger can be assigned one of eight categories—and 1 bit for views. In addition, event-level reports don't support encoding of high-fidelity trigger-side data, such as a specific price or trigger time. Because attribution happens on device, there is no support for cross-device analytics in the event-level reports.

The event-level report contains data such as the following:

• Destination: Advertiser app package name or eTLD+1 where the trigger happened
• Attribution Source ID: The same attribution source ID that was used for registering an attribution source
• Trigger type: 1 or 3 bits of low-fidelity trigger data, depending on the type of attribution source

Privacy-preserving mechanisms applied to all reports

The following limits are applied after priorities regarding attribution sources and triggers are taken into consideration.

Limits on number of ad techs

There are limits on the number of ad techs that can register or receive reports from the API, with a current proposal of the following:

• 100 ad techs with attribution sources per {source app, destination app, 30 days, device}.
• 10 ad techs with attributed triggers per {source app, destination app, 30 days, device}.
• 20 ad techs can register a single attribution source or trigger (via Attribution-Reporting-Redirect )

Limits on number of unique destinations

These limits make it difficult for a set of ad techs to collude by querying a large number of apps to understand a given user's app usage behavior.

• Across all registered sources, across all ad techs, the API supports no more than 200 unique destinations, per source app, per minute.
• Across all registered sources, for a single ad tech, the API supports no more than 50 unique destinations, per source app, per minute. This limit prevents one ad tech from using up the entire budget from the previously mentioned rate limit.

Expired sources don't count towards the rate limits.

One reporting origin per source app per day

A given ad tech platform may only use one reporting origin to register sources on a publisher app, for a given device, on the same day. This rate limit prevents ad techs from using multiple reporting origins to access additional privacy budget.

Consider the following scenario, where a single ad tech wants to use multiple reporting origins to register sources on a publisher app, for a single device.

1. Ad tech A's reporting origin 1 registers a source on App B
2. 12 hours later, ad tech A's reporting origin 2 attempts to register a source on App B

The second source, for Ad tech A's reporting origin 2, would be rejected by the API. Ad tech A's reporting origin 2 wouldn't be able to successfully register a source on the same device on App B until the following day.

Cooldown and rate limits

To limit the amount of user identity leakage between a {source, destination} pair, the API throttles the amount of total information sent in a given time period for a user.

The current proposal is to limit each ad tech to 100 attributed triggers per {source app, destination app, 30 days, device}.

Number of unique destinations

The API limits the number of destinations that an ad tech can try to measure. The lower the limit, the harder it is for an ad tech to use the API to attempt to measure user browsing activity that isn't associated with ads being shown.

The current proposal is to limit each ad tech to 100 distinct destinations with non-expired sources per source app.

Privacy-preserving mechanisms applied to event-level reports

Limited fidelity of trigger data

The API provides 1 bit for view-through triggers and 3 bits for click-through triggers. Attribution sources continue to support the full 64 bits of metadata.

You should evaluate if and how to reduce the information expressed in triggers so they work with the limited number of bits available in event-level reports.

Framework for differential privacy noise

A goal of this API is to allow event-level measurement to satisfy local differential privacy requirements by using k-randomized responses to generate a noisy output for each source event.

Noise is applied on whether an attribution source event is reported truthfully. An attribution source is registered on the device with probability $ 1-p $ that the attribution source is registered as normal, and with probability $ p $ that the device randomly chooses among all possible output states of the API (including not reporting anything at all, or reporting multiple fake reports).

The k-randomized response is an algorithm that is epsilon differentially private if the following equation is satisfied:

\[ p = \frac{k}{k + e^ε - 1} \]

For low values of ε, the true output is protected by the k-randomized response mechanism. Exact noise parameters are works in progress and are subject to change based on feedback, with a current proposal of the following:

• p=0.24% for navigation sources
• p=0.00025% for event sources

Limits on available triggers (conversions)

There are limits on the number of triggers per attribution source, with a current proposal of the following:

• 1-2 triggers for ad view attribution sources (2 triggers only available in the case of post-install attribution)
• 3 triggers for click ad attribution sources

Note: This describes the default API behavior for the number of attributions per source using event-level reporting. With the introduction of flexible event-level reporting in October 2023, ad techs can now configure this dimension of their reporting based on what works best for their use case.

Specific time windows for sending reports (default behaviour)

Event-level reports for ad view attribution sources are sent 1 hour after the source expires. This expiry date can be configured, but it cannot be less than 1 day or more than 30 days. If two triggers are attributed to an ad view attribution source (via post-install attribution )), event-level reports can be sent at the reporting window intervals specified as follows.

Event-level reports for ad click attribution sources cannot be configured and are sent before or when the source expires, at specified points in time relative to when the source was registered. The time between the attribution source and expiry is split into multiple reporting windows. Each reporting window has a deadline (from the attribution source time). At the end of each reporting window, the device collects all the triggers that have occurred since the previous reporting window and sends a scheduled report. The API supports the following reporting windows:

• 2 days: The device collects all the triggers that occurred at most 2 days after the attribution source was registered. The report is sent 2 days and 1 hour after the attribution source is registered.
• 7 days: The device collects all the triggers that occurred more than 2 days but no more than 7 days after the attribution source was registered. The report is sent 7 days and 1 hour after the attribution source is registered.
• A custom length of time, defined by the "expiry" attribute of an attribution source. The report is sent 1 hour after the specified expiry time. This value cannot be less than 1 day or more than 30 days.

Note: This describes the default API behavior for event-level reporting windows. With the introduction of flexible event-level reporting in October 2023, ad techs can now configure this dimension of their reporting based on what works best for their use case.

Flexible event-level configuration

The default configuration for event level reporting is what ad techs are advised to start using as they begin utility testing, but may not be ideal for all use cases. The Attribution Reporting API will support optional, and more flexible configurations so that ad techs have increased control over the structure of their event level reports and are able to maximize the utility of the data.

This additional flexibility will be introduced into the Attribution Reporting API in two phases:

• Phase 1: Lite flexible event level configuration
  • This version provides a subset of the full features, and can be used independently of Phase 2.
• Phase 2: Full version of flexible event level configuration

Phase 1 (Lite flexible event level) could be used to:

• Vary the frequency of reports by specifying the number of reporting windows
• Vary the number of attributions per source registration
• Reduce the amount of total noise by decreasing the above parameters
• Configure reporting windows rather than using the defaults

Phase 2 (Full flexible event level) could be used to do all of the capabilities in Phase 1 and:

• Vary the trigger data cardinality in a report
• Reduce the amount of total noise by decreasing the trigger data cardinality

Reducing one dimension of the default configuration allows the ad tech to increase another dimension. Alternatively, the total amount of noise in an event level report may be reduced by net decreasing the parameters mentioned above.

In addition to dynamically setting noise levels based on an ad tech's chosen configuration, we will have some parameter limits to avoid large computation costs and configurations with too many output states (where noise will increase considerably). Here is an example set of restrictions. Feedback is encouraged on the [design proposal][50]:

• Maximum of 20 total reports, globally and per trigger_data
• Maximum of 5 possible reporting windows per trigger_data
• Maximum of 32 trigger data cardinality (not applicable for Phase 1: Lite Flexible Event Level)

As ad techs start using this feature, be advised that using extrema values may result in a large amount of noise, or failure to register if privacy levels are not met.

Note: Phase 1 (Lite flexible event level) was released in beta in October 2023. Phase 2 (Full flexible event level) is scheduled for release in beta later in Q1 2024.

Aggregatable reports

Before using aggregatable reports, you must set up your cloud account and start receiving aggregatable reports.

Aggregatable reports provide higher-fidelity trigger data from the device more quickly, beyond what is offered for event-level reports . This higher-fidelity data can only be learned in aggregate , and isn't associated with a particular trigger or user. Aggregation keys are up to 128 bits, and this allows aggregatable reports to support reporting use cases such as the following:

• Reports for trigger values, such as revenue
• Handling more trigger types

In addition, aggregatable reports use the same source-prioritized attribution logic as event-level reports, but they support more conversions attributed to a click or view.

The overall design of how the Attribution Reporting API prepares and sends aggregatable reports, shown in the diagram, is as follows:

1. The device sends encrypted aggregatable reports to the ad tech. In a production environment, ad techs can't use these reports directly.
2. The ad tech sends a batch of aggregatable reports to the aggregation service for aggregation.
3. The aggregation service reads a batch of aggregatable reports, decrypts and aggregates them.
4. The final aggregates are sent back to the ad tech in a summary report .

Process that the Attribution Reporting API uses to prepare and send aggregatable reports.

Aggregatable reports contain the following data related to attribution sources:

• Destination: The app's package name or eTLD+1 web URL where the trigger happened.
• Date: The date when the event represented by the attribution source occurred.
• Payload: Trigger values, collected as encrypted key/value pairs, which is used in the trusted aggregation service to compute aggregations.

Aggregation services

The following services provide data aggregation capabilities and safeguard against unauthorized access to aggregated data..

These services are managed by different parties, which are described in more detail later on this page:

• The aggregation service is the only one that ad techs are expected to deploy.
• The key management and aggregatable report accounting services are run by trusted parties called coordinators . These coordinators attest that the code running the aggregation service is the publicly-available code provided by Google and that all aggregation service users have the same key and aggregatable report accounting services applied to them.

Aggregation service

Ad tech platforms must, in advance, deploy an aggregation service that's based on binaries provided by Google.

This aggregation service operates in a Trusted Execution Environment (TEE) hosted in the cloud. A TEE offers the following security benefits:

• It ensures that the code operating in the TEE is the specific binary offered by Google. Unless this condition is satisfied, the aggregation service can't access the decryption keys it needs to operate.
• It offers security around the running process, isolating it from external monitoring or tampering.

These security benefits make it safer for an aggregation service to perform sensitive operations, such as accessing encrypted data.

For more information on the design, workflow, and security considerations of the aggregation service, see the aggregation service document on GitHub.

Key management service

This service verifies that an aggregation service is running an approved version of the binary and then provides the aggregation service in the ad tech with the correct decryption keys for their trigger data.

Aggregatable report accounting

This service tracks how often an ad tech's aggregation service accesses a specific trigger—which can contain multiple aggregation keys—and limits access to the appropriate number of decryptions. Refer to the Aggregation Service for the Attribution Reporting API design proposal for details.

Aggregatable Reports API

The API for creating contributions to aggregatable reports uses the same base API as when registering an attribution source for event-level reports. The following sections describe the extensions of the API.

Register the aggregatable source data

When the API makes a request to the Attribution Source URI, the ad tech can register a list of aggregation keys, named histogram_contributions , by responding with a new field called aggregation_keys in HTTP header Attribution-Reporting-Register-Source , with key as the key_name and value as key_piece :

• (Key) Key name: A string for the name of the key. Used as a join key to combine with trigger-side keys to form the final key.
• (Value) Key piece: A bitstring value for the key.

The final histogram bucket key is fully defined at trigger time by performing a binary OR operation on these pieces and the trigger-side pieces.

Final keys are restricted to a maximum of 128 bits; keys longer than this are truncated. This means that hex strings in the JSON should be limited to at most 32 digits.

Learn more about how aggregation keys are structured and how you can configure aggregation keys.

In the following example, an ad tech uses the API to collect the following:

• Aggregate conversion counts at a campaign level
• Aggregate purchase values at a geo level

// This is where the Attribution-Reporting-Register-Source object appears when
// an ad tech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Source:
…
aggregation_keys: {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).

  "campaignCounts": "0x159",
  // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue"
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
  "geoValue": "0x5"
}

Register the aggregatable trigger

Trigger registration includes two additional fields.

The first field is used to register a list of aggregate keys on the trigger side. The ad tech should respond back with the aggregatable_trigger_data field in HTTP header Attribution-Reporting-Register-Trigger , with the following fields for each aggregate key in the list:

• Key piece: A bitstring value for the key.
• Source keys: A list of strings with the names of attribution source side keys that the trigger key should be combined with to form the final keys.

The second field is used to register a list of values which should contribute to each key. The ad tech should respond back with the aggregatable_values field in the HTTP header Attribution-Reporting-Register-Trigger . The second field is used to register a list of values which should contribute to each key, which can be integers in the range $ [1, 2^{16}] $.

Each trigger can make multiple contributions to the aggregatable reports. The total amount of contributions to any given source event is bound by an $ L1 $ parameter, which is the maximum sum of contributions (values) across all aggregate keys for a given source. $ L1 $ refers to the L1 sensitivity or norm of the histogram contributions per source event. Exceeding these limits causes future contributions to silently drop. The initial proposal is to set $ L1 $ to $ 2^{16} $ (65536).

The noise in the aggregation service is scaled in proportion to this parameter. Given this, it is recommended to appropriately scale the values reported for a given aggregate key, based on the portion of $ L1 $ budget allocated to it. This approach helps ensure that the aggregate reports retain the highest possible fidelity when noise is applied. This mechanism is highly flexible and can support many aggregation strategies.

In the following example, the privacy budget is split equally between campaignCounts and geoValue by splitting the $ L1 $ contribution to each:

// This is where the Attribution-Reporting-Register-Trigger object appears
// when an ad tech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Trigger:{
    …
    "aggregatable_trigger_data":

    [
    // Each dictionary independently adds pieces to multiple source keys.
    {
    // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
    // A 9-bit offset is needed because there are 511 possible campaigns, which
    // will take up 9 bits in the resulting key.
        "key_piece": "0x400",// Conversion type purchase = 2
        // Apply this key piece to:
        "source_keys": ["campaignCounts"]
    },
    {
    // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
    // A 7-bit offset is needed because there are ~100 regions for the geo key,
    // which will take up 7 bits of space in the resulting key.
        "key_piece": "0xA80",
        // Apply this key piece to:
        "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
    }
    ]

    // Specify an amount of an abstract value which can be integers in [1, 2^16] to
    // contribute to each key that is attached to aggregation keys in the order that
    // they're generated.
    aggregatable_values:
    {
    // Privacy budget for each key is L1 / 2 = 2^15 (32768).
    // Conversion count was 1.
    // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
        "campaignCounts": 32768,

    // Purchase price was $52.
    // Purchase values for the app range from $1 to $1,024 (integers only).
    // Scaling factor applied is 32768 / 1024 = 32.
    // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
        "geoValue": 1664
    }
}

The preceding example generates the following histogram contributions:

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

Note: filters still apply to aggregatable reports, and each dictionary in aggregatable_trigger_data can still optionally have conversion filters applied to it, just like the trigger filters for event-level reports.

The scaling factors can be inverted in order to obtain the correct values, modulo noise that is applied:

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

حریم خصوصی متفاوت

A goal of this API is to have a framework which can support differentially private aggregate measurement. This can be achieved by adding noise proportional to the $ L1 $ budget, such as picking noise with the following distribution:

\[ Laplace(\frac{L1}{ε}) \]

Protected Audience API and Attribution Reporting API Integration

Cross-API integration across the Protected Audience and Attribution Reporting APIs enables adtechs to evaluate their attribution performance across various remarketing tactics in order to understand which types of audiences deliver the highest ROI.

Through this cross-API integration, adtechs can:

• Create a key-value map of URIs to be used for both 1) interaction reporting and 2) source registration.
• Include CustomAudience in their source-side key mapping for aggregate summary reporting (using the Attribution Reporting API).

When a user sees or clicks on an ad:

• The URL used to report those interactions using Protected Audience will also be used to register a view or click as an eligible source with the Attribution Reporting API.
• The ad tech may choose to pass CustomAudience (or other relevant contextual information about the ad such as ad placement or view duration) using that URL so this metadata can propagate down to summary reports when the ad tech is reviewing aggregate campaign performance.

For more information on how this is enabled within Protected Audience, see the relevant section of the Protected Audience API explainer .

Registration priority, attribution, and reporting examples

This example showcases a set of user interactions and how ad tech defined attribution source and trigger priorities could affect attributed reports. In this example, we assume the following:

• All attribution sources and triggers are registered by the same ad tech, for the same advertiser.
• All attribution sources and triggers are happening during the first event reporting window (within 2 days of initially displaying the ads in a publisher app).

Consider the case where a user does the following:

1. The user sees an ad. Ad tech registers an attribution source with the API, with a priority of 0 (view #1).
2. The user sees an ad, registered with a priority of 0 (view #2).
3. The user clicks an ad, registered with a priority of 1 (click #1).
4. The user converts (reaches landing page) in an advertiser app. The ad tech registers a trigger with the API, with a priority of 0 (conversion #1).
   • As triggers are registered, the API performs attribution first before generating reports.
   • There are 3 attribution sources available: view #1, view #2, and click #1. The API attributes this trigger to click #1 because it's the highest priority and most recent.
   • View #1 and view #2 are discarded and are no longer eligible for future attribution.
5. The user adds an item to their cart in the advertiser app, registered with a priority of 1 (conversion #2).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.
6. The user adds an item to their cart in the advertiser app, registered with a priority of 1 (conversion #3).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.
7. The user adds an item to their cart in the advertiser app, registered with a priority of 1 (conversion #4).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.
8. The user makes a purchase in the advertiser app, registered with a priority of 2 (conversion #5).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.

Event-level reports have the following characteristics:

• By default, the first 3 triggers attributed to a click and the first trigger attributed to a view are sent out after applicable reporting windows.
• Within the reporting window, if there are triggers registered with higher priority, those take precedence and replace the most recent trigger.
• In the preceding example, the ad tech receives 3 event reports after the 2-day reporting window, for conversion #2, conversion #3, and conversion #5.
  • All 5 triggers are attributed to click #1. By default, the API would send out reports for the first 3 triggers: conversion #1, conversion #2, and conversion #3.
  • However, conversion #4's priority ( 1 ) is higher than conversion #1's priority ( 0 ). Conversion #4's event report replaces conversion #1's event report to be sent out.
  • Additionally, conversion #5's priority ( 2 ) is higher than any other trigger. Conversion #5's event report replaces conversion #4's report to be sent out.

Aggregatable reports have the following characteristics:

• Encrypted aggregatable reports are sent to the ad tech as soon as they are processed, a few hours after the triggers are registered.

  As an ad tech, you create their batches based on the information that comes unencrypted in your aggregatable reports. This information is contained in the shared_info field in your aggregatable report, and includes timestamp and reporting origin. You can't batch based on any encrypted information in your aggregation key-value pairs. Some simple strategies you can follow are batching reports daily or weekly. Ideally, batches should contain at least 100 reports each.

• It's up to the ad tech on when and how to batch the aggregatable reports and send to the aggregation service.

• Compared to event-level reports, encrypted aggregatable reports can attribute more triggers to a source.

• In the preceding example, 5 aggregatable reports are sent out, one for each registered trigger.

Transitional debugging reports

The Attribution Reporting API is a new and fairly complex way to do attribution measurement without cross-app identifiers. As such, we are supporting a transitional mechanism to learn more information about attribution reports when the advertising ID is available (the user has not opted out of personalization using the advertising ID and the publisher or advertiser app has declared AdID permissions) . This ensures that the API can be fully understood during roll-out, help flush out any bugs, and more easily compare the performance to advertising ID-based alternatives. There are two types of debugging reports: attribution-success and verbose.

Read the guide on transitional debugging reports for details on debugging reports with app-to-web and web-to-app measurement.

Attribution-success debugging reports

Source and trigger registrations both accept a new 64-bit debug_key field (formatted as a String), which the ad tech populates. source_debug_key and trigger_debug_key are passed unaltered in both event-level and aggregate reports.

If a report is created with both source and trigger debug keys, a duplicate debug report is sent with limited delay to a .well-known/attribution-reporting/debug/report-event-attribution endpoint. The debug reports are identical to normal reports, including both debug key fields. Including these keys in both allows tying normal reports to the separate stream of debug reports.

• For event-level reports:
  • Duplicate debug reports are sent with limited delay and therefore aren't suppressed by limits on available triggers , which allows ad tech to understand the impact of those limits for event-level reports.
  • Event-level reports associated with false trigger events will not have trigger_debug_key s. This allows ad tech to more closely understand how noise is applied in the API.
• For aggregatable reports:
  • We will support a new debug_cleartext_payload field which contains the decrypted payload, only if both source_debug_key and trigger_debug_key are set.

Verbose debugging reports

Verbose debugging reports allow developers to monitor certain failures in the attribution source or trigger registrations. These debugging reports are sent with limited delay after attribution source or trigger registrations to a . well-known/attribution-reporting/debug/verbose endpoint.

Each verbose report contains the following fields:

• Type : what caused the report to be generated. See the full list of verbose report types .
  • In general, there are source verbose reports and trigger verbose reports.
  • Source verbose reports require the advertising ID to be available to the publisher app, and trigger verbose reports require the advertising ID to be available to the advertiser app.
  • Trigger verbose reports (with the exception of trigger-no-matching-source ) can optionally include the source_debug_key . This can only be included if the advertising ID is also available to the publisher app.
• Body : The report's body, which depends on its type.

Ad techs need to opt in to receive verbose debugging reports using a new debug_reporting dictionary field in the Attribution-Reporting-Register_Source and Attribution-Reporting-Register-Trigger headers.

• Source verbose reports require opt-in on the source registration header only.
• Trigger debug reports require opt-in on the trigger registration header only.

How to use debug reports

If a conversion took place (according to your existing measurement system) and a debug report was received for that conversion, this means the trigger was successfully registered.

For each debug attribution report, check if you're receiving a regular attribution report that matches the two debug keys.

When there's no match, it can be for a number of reasons.

Works as intended:

• Privacy-preserving API behaviors:
  • A user hits the report rate limit—causing all subsequent reports to not be sent in the time period; or a source is removed due to the pending destination limit.
  • For event-level reports: the report is subject to randomized response (noise) and is suppressed, or you may receive a randomized report.
  • For event-level reports: the limit of three (for clicks) or one (for views) reports has been reached, and subsequent reports have no explicit priority set, or a priority that is lower than existing reports.
  • The contribution limits for aggregatable reports have been exceeded.
• Ad tech-defined business logic:
  • A trigger is filtered out via filters or priority rules.
• Time delays or interactions with network availability (eg, the user turns off their device for an extended period of time).

Unintended causes:

• Implementation issues:
  • The source header is misconfigured.
  • The trigger header is misconfigured.
  • Other configuration issues.
• Device or network issues:
  • Failures due to network conditions.
  • Source or trigger registration response doesn't reach the client.
  • API bug.

Future considerations & open questions

The Attribution Reporting API is a work in progress. We're also exploring future potential features, such as non-last-click attribution models and cross-device measurement use cases.

Additionally, we'd like to seek feedback from the community on a few issues:

1. Are there any use cases where you'd like the API to send out reports for the verified install? These reports would count against ad tech platforms' respective rate limits.
2. Do you foresee any difficulties with passing the InputEvent from the app to ad tech for source registration?
3. Do you have any special attribution use cases for pre-loaded apps or re-installed apps?

،

Note: This document reflects the Privacy Sandbox on Android's current design proposals and is subject to further change. We encourage your feedback and comments to assist in these efforts.

به روز رسانی های اخیر

• Updated the list of upcoming changes and known issues

• Introduced lite flexible event-level configuration, as a bridge to the full flexible event-level configuration

• Starting in September 2023, registerWebSource , registerWebTrigger , registerAppSource and registerAppTrigger must use strings for fields that expect a numeric value (such as priority , source_event_id , debug_key , trigger_data , deduplication_key , etc.)

• In Q4 2023, Google Cloud support in the Android Attribution Reporting API will be added to generate summary reports using Aggregation Service on Google Cloud, more specific timing reflected here. See the deployment guide for more information on setting up Aggregation Service with Google Cloud.

• New privacy preserving rate limits for number of unique destinations.

• Updated functionality for lookback window trigger filters will be coming in Q1 2024, see the note for further information.

نمای کلی

Today, it's common for mobile attribution and measurement solutions to use cross-party identifiers, such as Advertising ID. The Attribution Reporting API is designed to provide improved user privacy by removing reliance on cross-party user identifiers, and to support key use cases for attribution and conversion measurement across apps and the web.

This API has the following structural mechanisms that offer a framework for improving privacy, which later sections on this page describe in more detail:

• Limits the number of bits available for event-level reports

• Enables higher-fidelity conversion data only in aggregatable reports

• Introduces rate limits for available triggers (conversions) and the number of ad techs that can be associated with a single attribution source

• Incorporates various noise adding techniques

The preceding mechanisms limit the ability to link user identity across two different apps or domains.

The Attribution Reporting API supports the following use cases:

• Conversion reporting: Help advertisers measure the performance of their campaigns by showing them conversion (trigger) counts and conversion (trigger) values across various dimensions, such as by campaign, ad group, and ad creative.
• Optimization: Provide event-level reports that support optimization of ad spend, by providing per-impression attribution data that can be used to train ML models.
• Invalid activity detection: Provide reports that can be used in invalid traffic and ad fraud detection and analysis.

At a high level, the Attribution Reporting API works as follows, which later sections of this document describe in more detail:

1. The ad tech completes an enrollment process to use the Attribution Reporting API.
2. The ad tech registers attribution sources —ad clicks or views—with the Attribution Reporting API.
3. The ad tech registers triggers —user conversions on the advertiser app or website—with the Attribution Reporting API.
4. The Attribution Reporting API matches triggers to attribution sources—a conversion attribution—and one or more triggers are sent off-device through event-level and aggregatable reports to ad techs.

Note: For more information about how to implement this design for an app-to-app attribution use case, read the cross-network attribution section of the Attribution Reporting API Developer's Guide. To learn how to implement an app-to-web or web-to-app use case, read the cross app and web measurement design proposal .

Get access to Attribution Reporting APIs

Ad tech platforms need to enroll to access the Attribution Reporting APIs, see Enroll for a Privacy Sandbox account for more information.

Register an attribution source (click or view)

The Attribution Reporting API refers to ad clicks and views as attribution sources . To register an ad click or ad view, call registerSource() . This API expects the following parameters:

• Attribution source URI: The platform issues a request to this URI in order to fetch metadata associated with the attribution source.
• Input event: Either an InputEvent object (for a click event) or null (for a view event).

When the API makes a request to the Attribution Source URI, the ad tech should respond with the attribution source metadata in a new HTTP header Attribution-Reporting-Register-Source , with the following fields:

• Source event ID : This value represents the event-level data associated with this attribution source (ad click or view). Must be a 64-bit unsigned integer formatted as a string.
• Destination : An origin whose eTLD+1 or app package name where the trigger event happens.
• Expiry (optional) : Expiry, in seconds, for when the source should be deleted off the device. Default is 30 days, with a minimum value of 1 day and a maximum value of 30 days. This is rounded to the nearest day. Can be formatted as either a 64-bit unsigned integer or string.
• Event report window (optional) : Duration in seconds after source registration during which event reports may be created for this source. If the event report window has passed, but the expiry has not yet passed, a trigger can still be matched with a source, but an event report is not sent for that trigger. Cannot be greater than Expiry. Can be formatted as either a 64-bit unsigned integer or string.
• Aggregatable report window (optional) : Duration in seconds after source registration during which aggregatable reports may be created for this source. Cannot be greater than Expiry. Can be formatted as either a 64-bit unsigned integer or string.
• Source priority (optional) : Used to select which attribution source a given trigger should be associated with, in case multiple attribution sources could be associated with the trigger. Must be a 64-bit signed integer formatted as a string.
  
  When a trigger is received, the API finds the matching attribution source with the highest source priority value and generates a report. Each ad tech platform can define its own prioritization strategy. For more details on how priority impacts attribution, see the prioritization example section.
  
  Higher values indicate higher priorities.
• Install and post-install attribution windows (optional): Used to determine attribution for post-install events , described later on this page.
• Filter data (optional): Used to selectively filter some triggers, effectively ignoring them. For more details, see the trigger filters section on this page.
• Aggregation keys (optional): Specify segmentation to be used for aggregatable reports .

Optionally, the attribution source metadata response may include additional data in the Attribution reporting redirects header. The data contains redirect URLs, which allow multiple ad techs to register a request .

The developer guide includes examples that show how to accept source registration .

The following steps show an example workflow:

1. The ad tech SDK calls the API to initiate attribution source registration, specifying a URI for the API to call:

   registerSource(
       Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
       myClickEvent);
   

2. The API makes a request to https://adtech.example/attribution_source? AD_TECH_PROVIDED_METADATA , using one of the following headers:

   <!-- For click events -->
   Attribution-Reporting-Source-Info: navigation
   
   <!-- For view events -->
   Attribution-Reporting-Source-Info: event
   

3. This ad tech's HTTPS server replies with headers containing the following:

   Attribution-Reporting-Register-Source: {
       "destination": "android-app://com.advertiser.example",
       "source_event_id": "234",
       "expiry": "60000",
       "priority": "5"
   }
   Attribution-Reporting-Redirect:
   https://adtechpartner1.example?their_ad_click_id=567
   Attribution-Reporting-Redirect:
   https://adtechpartner2.example?their_ad_click_id=890
   

4. The API makes a request to each URL specified in Attribution-Reporting-Redirect . In this example, two ad tech partner URLs are specified, so the API makes one request to https://adtechpartner1.example?their_ad_click_id=567 and another request to https://adtechpartner2.example?their_ad_click_id=890 .

5. This ad tech's HTTPS server replies with headers containing the following:

   Attribution-Reporting-Register-Source: {
       "destination": "android-app://com.advertiser.example",
       "source_event_id": "789",
       "expiry": "120000",
       "priority": "2"
   }
   

   Note: ad techs' replies can specify different metadata in the Attribution-Reporting-Register-Source header.

Three navigation (click) attribution sources are registered based on the requests shown in the previous steps.

Register an attribution source from WebView

WebView supports the use case where an app is rendering an ad within a WebView. This is handled by WebView directly calling registerSource() as a background request. This call associates the attribution source to the app instead of the top-level origin. Registering sources from embedded web content within a browser context is also supported; both API callers and apps need to adjust settings to do so. See Register attribution source and trigger from WebView for instructions for API callers and Attribution source and trigger registration from WebView for instructions for apps.

Since ad techs use common code across Web and WebView, WebView follows HTTP 302 redirects and passes on the valid registrations to the platform. We don't plan to support the Attribution-Reporting-Redirect header for this scenario, but reach out if you have an impacted use case.

Note: To allow WebViews to use the Attribution Reporting API, the embedding app needs to be configured with the correct permissions .

Register a trigger (conversion)

Ad tech platforms can register triggers —conversions such as installs or post-install events—using the registerTrigger() method.

The registerTrigger() method expects the Trigger URI parameter. The API issues a request to this URI to fetch metadata associated with the trigger.

The API follows redirects. The ad tech server response should include an HTTP header called Attribution-Reporting-Register-Trigger , which represents information on one or more registered triggers. The header's content should be JSON-encoded and include the following fields:

• Trigger data: Data to identify the trigger event (3 bits for clicks, 1 bit for views). Must be a 64-bit signed integer formatted as a string.

• Trigger priority (optional): Represents the priority of this trigger compared to other triggers for the same attribution source. Must be a 64-bit signed integer formatted as a string. For more details on how priority impacts reporting, see the prioritization section section.

• Deduplication key (optional): Used to identify cases where the same trigger is registered multiple times by the same ad tech platform, for the same attribution source. Must be a 64-bit signed integer formatted as a string.

• Aggregation keys (optional): A list of dictionaries which specifies aggregation keys and which aggregatable reports should have their value aggregated.

• Aggregation values (optional): A list of amounts of value which contribute to each key.

• Filters (optional): Used to selectively filter triggers or trigger data. For more details, see the trigger filters section on this page.

Optionally, the ad tech server response may include additional data in the Attribution Reporting Redirects header. The data contains redirect URLs, which allow multiple ad techs to register a request .

Multiple ad techs can register the same trigger event using either redirects in the Attribution-Reporting-Redirect field or multiple calls to the registerTrigger() method. We recommend that you use the deduplication key field to avoid including duplicate triggers in reports in the case that the same ad tech provides multiple responses for the same trigger event. Learn more about how and when to use a deduplication key .

The Developer's Guide includes examples that show how to accept trigger registration .

The following steps show an example workflow:

1. The Ad tech SDK calls the API to initiate trigger registration using a pre-enrolled URI. See Enroll for a Privacy Sandbox account for more information.

   registerTrigger(
       Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
   

2. The API makes a request to https://adtech.example/attribution_trigger? AD_TECH_PROVIDED_METADATA .

3. This ad tech's HTTPS server replies with headers containing the following:

   Attribution-Reporting-Register-Trigger: {
       "event_trigger_data": [{
       "trigger_data": "1122",
       // This returns 010 for click-through conversions (CTCs) and 0 for
       // view-through conversions (VTCs) in reports
       "priority": "3",
       "deduplication_key": "3344"
       }],
   }
   Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567
   

   Note: Only the ad tech that initiates the API call can specify partners in Attribution-Reporting-Redirect .

4. The API makes a request to each URL specified in Attribution-Reporting-Redirect . In this example, only one URL is specified, so the API makes a request to https://adtechpartner.example?app_install=567 .

5. This ad tech's HTTPS server replies with headers containing the following:

   Attribution-Reporting-Register-Trigger: {
   "event_trigger_data":[{
     "trigger_data": "5566",
     "priority": "3",
     "deduplication_key": "3344"
   }]
   }
   

   Two triggers are registered based on the requests in the previous steps.

Attribution capabilities

The following sections explain how the Attribution Reporting API matches conversion triggers to attribution sources.

Source-prioritized attribution algorithm applied

The Attribution Reporting API employs a source-prioritized attribution algorithm to match a trigger (conversion) to an attribution source.

Priority parameters provide ways to customize the attribution of triggers to sources:

• You can attribute triggers to certain ad events over others. For example, you may choose to place more emphasis on clicks rather than views, or focus on events from certain campaigns.
• You can configure the attribution source and trigger such that, if you hit rate limits, you're more likely to receive the reports that are more important to you. For example, you might want to make sure that biddable conversions or high-value conversions are more likely to appear in these reports.

In the case where multiple ad techs register an attribution source , as described later on this page, this attribution happens independently for each ad tech. For each ad tech, the attribution source with the highest priority is attributed with the trigger event. If there are multiple attribution sources with the same priority, the API picks the last registered attribution source. Any other attribution sources, that aren't picked are discarded and are no longer eligible for future trigger attribution.

Trigger filters

Source and trigger registration includes additional optional features to do the following:

• Selectively filter some triggers, effectively ignoring them.
• Choose trigger data for event-level reports based on source data.
• Choose to exclude a trigger from event-level reports.

To selectively filter triggers, the ad tech can specify filter data, consisting of keys and values, during source and trigger registration. If the same key is specified for both the source and trigger, then the trigger is ignored if the intersection is empty. For example, a source can specify "product": ["1234"] , where product is the filter key and 1234 is the value. If the trigger filter is set to "product": ["1111"] , then the trigger is ignored. If there is no trigger filter key matching product , then the filters are ignored.

Another scenario where ad tech platforms may want to selectively filter triggers is to force a shorter expiry window. On trigger registration, an ad tech can specify (in seconds) a lookback window from when the conversion happened; for example, a 7 day lookback window would be defined as: "_lookback_window": 604800 // 7d

To decide if a filter matches, the API will first check the lookback window. If available, the duration since the source was registered must be smaller or equal to the lookback window duration.

Note: The lookback filter logic and functionality described will be in effect in Q124. You can find more specific detail on release timing . Previous logic required lookback windows to be specified by the hour, on both the source and trigger side. This updated feature logic is backwards incompatible, meaning sources using the previous "_lookback_window" key won't be successfully registered.

Ad tech platforms can also choose trigger data based on source event data. For example, source_type is automatically generated by the API as either navigation or event . During trigger registration, trigger_data can be set as one value for "source_type": ["navigation"] and as a different value for "source_type": ["event"] .

Triggers are excluded from event-level reports if any of the following are true:

• There is no trigger_data specified.
• Source and trigger specify the same filter key, but the values don't match. Note that, in this case, the trigger is ignored for both event-level and aggregatable reports.

Post-install attribution

In some cases, there is a need for post-install triggers to be attributed to the same attribution source that drove the install, even if there are other eligible attribution sources that occurred more recently.

The API can support this use case by allowing ad techs to set a post-install attribution period:

• When registering an attribution source, specify an install attribution window during which installs are expected (generally 2-7 days, accepted range 1 to 30 days). Specify this time window as a number of seconds.
• When registering an attribution source, specify a post-install attribution exclusivity window where any post-install trigger events should be associated with the attribution source that drove the install (generally 7-30 days, accepted range 0 to 30 days). Specify this time window as a number of seconds.
• The Attribution Reporting API validates when an app install happens and internally attributes the install to the source-prioritized attribution source. However, the install isn't sent to ad techs and doesn't count against the platforms' respective rate limits.
• App install validation is available for any downloaded app.
• Any future triggers that happen within the post-install attribution window are attributed to the same attribution source as the validated install, as long as that attribution source is eligible.

In the future, we might explore extending the design to support more advanced attribution models.

The following table shows an example of how ad techs may use post-install attribution. Assume all attribution sources and triggers are being registered by the same ad tech network, and all priorities are the same.

رویداد	Day when event occurs	یادداشت ها
1 را کلیک کنید	1	install_attribution_window is set to 172800 (2 days), and post_install_exclusivity_window is set to 864000 (10 days)
Verified Install	2	The API internally attributes verified installs, but those installs aren't considered triggers. Therefore, no reports are sent at this point.
Trigger 1 (First Open)	2	First trigger registered by ad tech. In this example, it represents a first open but can be any trigger type. Attributed to click 1 (matches attribution of verified install).
روی 2 کلیک کنید	4	Uses the same values for install_attribution_window and post_install_exclusivity_window as Click 1
Trigger 2 (Post Install)	5	Second trigger registered by ad tech. In this example, it represents a post-install conversion like a purchase. Attributed to click 1 (matches attribution of verified install). Click 2 is discarded and isn't eligible for future attribution.

The following list provides some additional notes regarding post-install attribution:

• If the verified install doesn't happen within the number of days specified by install_attribution_window , post-install attribution isn't applied.
• Verified installs aren't registered by ad techs and aren't sent out in reports. They don't count against an ad tech's rate limits. Verified installs are only used to identify the attribution source that is credited with the install.
• In the example from the preceding table, trigger 1 and trigger 2 represent a first open and a post-install conversion, respectively. However, ad tech platforms can register any type of trigger. In other words, the first trigger need not be a first open trigger.
• If more triggers are registered after the post_install_exclusivity_window expires, click 1 is still eligible for attribution, assuming it hasn't expired and hasn't reached its rate limits.
  • Click 1 may still lose, or be discarded, if a higher-priority attribution source is registered.
• If the advertiser app is uninstalled and reinstalled, the reinstall is counted as a new verified install.
• If click 1 was a view event instead, both the "first open" and post-install triggers are still attributed to it. The API restricts attribution to one trigger per view, except in the case of post-install attribution where up to two triggers per view are allowed. In the post-install attribution case, the ad tech could receive 2 different reporting windows (at 2 days or at source expiry).

All combinations of app- and web-based trigger paths are supported

The Attribution Reporting API enables attribution of the following trigger paths on a single Android device:

• App-to-app: The user sees an ad in an app, then converts in either that app or another installed app.
• App-to-web: The user sees an ad in an app, then converts in a mobile or app browser.
• Web-to-app: The user sees an ad in a mobile or app browser, then converts in an app.
• Web-to-web: The user sees an ad in a mobile or app browser, then converts in either the same browser or another browser on the same device.

We allow web browsers to support new web-exposed features, such as functionality that's similar to the Privacy Sandbox for the Web's Attribution Reporting API , which can call the Android APIs to enable attribution across app and web.

Learn about the changes that ad techs and apps need to make in order to support trigger paths for cross app and web measurement .

Prioritize multiple triggers for a single attribution source

A single attribution source can lead to multiple triggers. For example, a purchase flow could involve an "app install" trigger, one or more "add-to-cart" triggers, and a "purchase" trigger. Each trigger is attributed to one or more attribution sources according to the source-prioritized attribution algorithm , described later on this page.

There are limits on how many triggers can be attributed to a single attribution source . For more details, read the section on viewing measurement data in attribution reports later on this page.

In the cases where there are multiple triggers beyond these limits, it's useful to introduce prioritization logic to get back the most valuable triggers. For example, the developers of an ad tech might want to prioritize getting "purchase" triggers over "add-to-cart" triggers.

To support this logic, a separate priority field can be set on the trigger, and the highest priority triggers are picked before limits are applied, within a given reporting window.

Note: Lower-priority triggers which have already been reported always consume the budget.

Allow multiple ad techs to register attribution sources or triggers

It's common for more than one ad tech to receive attribution reports, generally to perform cross-network deduplication. Therefore, the API allows multiple ad techs to register the same attribution source or trigger. An ad tech must register both attribution sources and triggers to receive postbacks from the API, and attribution is done among the attribution sources and triggers that the ad tech has registered with the API.

Advertisers that want to use a third party to perform cross-network deduplication can continue doing so, using a technique similar to the following:

• Setting up an in-house server to register and receive reports from the API.
• Continuing to use an existing mobile measurement partner.

Attribution sources

Attribution source redirects are supported in the registerSource() method:

1. The ad tech that calls the registerSource() method can provide an additional Attribution-Reporting-Redirect field in their response, which represents the set of partner ad tech's redirect URLs.
2. The API then calls the redirect URLs so the attribution source can be registered by the partner ad techs.

Multiple partner ad tech URLs can be listed in the Attribution-Reporting-Redirect field, and partner ad techs cannot specify their own Attribution-Reporting-Redirect field.

The API also allows different ad techs to each call registerSource() .

محرک ها

For trigger registration, third parties are supported in a similar way: ad techs can either use the additional Attribution-Reporting-Redirect field, or they can each call the registerTrigger() method.

When an advertiser uses multiple ad techs to register the same trigger event, a deduplication key should be used. The deduplication key serves to disambiguate these repeated reports of the same event registered by the same ad tech platform. For example, an ad tech could have their SDK call the API directly to register a trigger and have their URL in the redirect field of another ad tech's call. If no deduplication key is provided, duplicate triggers may be reported back to each ad tech as unique.

Handle duplicate triggers

An ad tech may register the same trigger multiple times with the API. Scenarios include the following:

• The user performs the same action (trigger) multiple times. For example, the user browses the same product multiple times in the same reporting window.
• The advertiser app uses multiple SDKs for conversion measurement, which all redirect to the same ad tech. For example, the advertiser app uses two measurement partners, MMP #1 and MMP #2. Both MMPs redirect to ad tech #3. When a trigger happens, both MMPs register that trigger with the Attribution Reporting API. Ad tech #3 then receives two separate redirects—one from MMP #1 and one from MMP #2—for the same trigger.

In these cases, there are several ways to suppress event-level reports on duplicate triggers, to make it less likely to exceed the rate limits applied to event-level reports . The recommended way is to use a deduplication key.

Recommended method: deduplication key

The recommended method is for the advertiser app to pass a unique deduplication key to any ad techs or SDKs that it's using for conversion measurement. When a conversion happens, the app passes a deduplication key to the ad techs or SDKs. Those ad techs or SDKs then continue passing the deduplication key to redirects using a parameter in the URLs specified in Attribution-Reporting-Redirect .

Ad techs can choose to register only the first trigger with a given deduplication key, or can choose to register multiple triggers or all triggers. Ad techs can specify the deduplication_key when registering duplicate triggers.

If an ad tech registers multiple triggers with the same deduplication key and attributed source, only the first registered trigger is sent in the event-level reports. Duplicate triggers are still sent in encrypted aggregatable reports.

Alternate method: ad techs agree on per-advertiser trigger types

In situations where ad techs do not wish to use the deduplication key, or where the advertiser app cannot pass a deduplication key, an alternate option exists. All ad techs measuring conversions for a given advertiser need to work together to define different trigger types for each advertiser.

Ad techs that initiate the trigger registration call—for example, SDKs—include a parameter in URLs specified in Attribution-Reporting-Redirect , such as duplicate_trigger_id . That duplicate_trigger_id parameter can include information like the SDK name and the trigger type for that advertiser. Ad techs can then send a subset of these duplicate triggers to event-level reports. Ad techs can also include this duplicate_trigger_id in their aggregation keys.

Cross-network attribution example

In the example described in this section, the advertiser is using two serving ad tech platforms (Ad tech A and Ad tech B) and one measurement partner (MMP).

To start, Ad tech A, Ad tech B, and MMP must each complete enrollment to use the Attribution Reporting API. See Enroll for a Privacy Sandbox account for more information.

The following list provides a hypothetical series of user actions that each occur one day apart, and how the Attribution Reporting API handles those actions with respect to Ad tech A, Ad tech B, and MMP:

Day 1: User clicks on an ad served by Ad tech A

Ad tech A calls registerSource() with their URI. The API makes a request to the URI, and the click is registered with the metadata from Ad tech A's server response.

Ad tech A also includes MMP's URI in the Attribution-Reporting-Redirect header. The API makes a request to MMP's URI, and the click is registered with the metadata from MMP's server response.

Day 2: User clicks on an ad served by Ad tech B

Ad tech B calls registerSource() with their URI. The API makes a request to the URI, and the click is registered with the metadata from Ad tech B's server response.

Like Ad tech A, Ad tech B has also included MMP's URI in the Attribution-Reporting-Redirect header. The API makes a request to MMP's URI, and the click is registered with the metadata from the MMP's server response.

Day 3: User views an ad served by Ad tech A

The API responds in the same way that it did on Day 1, except that a view is registered for Ad tech A and MMP.

Day 4: User installs the app, which uses the MMP for conversion measurement

MMP calls registerTrigger() with their URI. The API makes a request to the URL, and the conversion is registered with the metadata from MMP's server response.

MMP also includes the URIs for Ad tech A and Ad tech B in the Attribution-Reporting-Redirect header. The API makes requests to Ad tech A and Ad tech B's servers, and the conversion is registered accordingly with the metadata from the server responses.

The following diagram illustrates the process described in the preceding list:

Example of how the Attribution Reporting API responds to a series of user actions.

Attribution works as follows:

• Ad tech A sets the priority of clicks higher than views and therefore gets the install attributed to the click on Day 1.
• Ad tech B gets the install attributed on Day 2.
• MMP sets the priority of clicks higher than views and gets the install attributed to the click on Day 2. Day 2's click is the highest priority, most recent ad event.

Cross-network attribution without redirects

While we recommend utilizing redirects to allow multiple ad techs to register attribution sources and triggers, we recognize that there may be scenarios where using redirects isn't feasible. This section will detail how to support cross-network attribution without redirects.

جریان سطح بالا

1. On source registration, the serving ad tech network shares their source aggregation keys.
2. On trigger registration, the advertiser or measurement partner chooses which source-side key pieces to use and specifies their attribution configuration.
3. Attribution is based on the attribution config, shared keys, and any sources that were actually registered by that advertiser or measurement partner (eg from another serving ad tech network that has enabled redirects).
4. If the trigger is attributed to a source from a non-redirecting serving ad tech, the advertiser or measurement partner can receive an aggregatable report that combines the source and trigger key pieces defined in step #2.

Source registration

On source registration, the serving ad tech network can choose to share their source aggregation keys or a subset of their source aggregation keys instead of redirecting. The serving ad tech is not required to actually use these source keys in their own aggregatable reports and can declare them only on behalf of the advertiser or measurement partner if needed.

Shared aggregation keys are available to any ad tech that registers a trigger for the same advertiser. However, it is up to the serving ad tech and the trigger measurement ad tech to collaborate on what types of aggregation keys are needed, their names, and how to decode the keys into readable dimensions.

Trigger registration

On trigger registration, the measurement ad tech chooses which source-side key pieces to apply to each trigger key piece, including any shared by serving ad techs.

Additionally, the measurement ad tech must also specify their waterfall attribution logic using a new attribution configuration API call. In this config, the ad tech can specify source priority, expiry, and filters for sources that they had no visibility into (for example, sources that did not use a redirect).

انتساب

The Attribution Reporting API performs source-prioritized, last-touch attribution for the measurement ad tech based on their attribution config, shared keys, and any sources they registered. به عنوان مثال:

• The user clicked on ads served by ad techs A, B, C, and D. The user then installed the advertiser's app, which uses a measurement ad tech partner (MMP).
• Ad tech A redirects its sources to the MMP.
• Ad techs B and C do not redirect, but share their aggregation keys.
• Ad tech D neither redirects nor shares aggregation keys.

The MMP registers a source from Ad tech A, and defines an attribution config that includes Ad tech B and Ad tech D.

Attribution for the MMP now includes:

• Ad tech A, since the MMP registered a source from that ad tech's redirect.
• Ad tech B, since Ad tech B shared keys and the MMP included it in their attribution config.

Attribution for the MMP does not include:

• Ad tech C, since the MMP did not include it in their attribution config.
• Ad tech D, since they did not redirect nor share aggregation keys.

Note: For more information about how to implement this design, read the Attribution Reporting API Developer's Guide .

اشکال زدایی

To support debugging for cross-network attribution without redirects, an additional field, shared_debug_key , is available for ad techs to set upon source registration. If set on the original source registration, it will also be set on the corresponding derived source as debug_key during trigger registration for cross-network attribution without redirects. This debug key is attached as source_debug_key in event and aggregate reports.

This debug feature will only be supported for cross-network attribution without redirects under the following scenarios:

• App to app measurement where AdId is permitted
• App to web measurement where AdId is permitted and matching across both the app source and the web trigger
• Web to web measurement (on the same browser app) when ar_debug ` is present on both source and trigger

Key discovery for cross-network attribution without redirects

Key discovery is intended to streamline how ad techs (usually MMPs) implement their attribution config for the purposes of cross-network attribution when one or several serving ad techs are using shared aggregation keys (as described in Cross-network attribution without redirects above).

When an MMP queries the Aggregation Service to generate summary reports for campaigns that include derived sources, Aggregation Service requires the MMP to specify the list of possible keys as input for the aggregation job. In some cases, the list of potential source aggregation keys may be very large, or unknown. Large lists of possible keys are challenging to track, and are also likely to be quite complex and costly to process. به مثال های زیر توجه کنید:

• List of all possible keys is large:
  • A serving ad network is executing a complex user acquisition initiative that includes 20 campaigns, each with 10 ad groups, and each ad group with 5 creatives that are refreshed every week based on performance.
• List of all possible keys is unknown:
  • A serving ad network is serving ads across many mobile apps where the full list of publisher app IDs is not known at campaign launch.
  • An advertiser is working across multiple serving ad networks that are not redirecting to the MMP on source registration; each serving ad network has a different key structure and values, which may not be shared in advance with the MMP.

With the introduction of key discovery:

• The Aggregation Service no longer requires a full enumeration of possible aggregation keys.
• Instead of having to specify the full list of possible keys, an MMP can create an empty (or partially empty) set of keys and set a threshold, so that only (non pre-declared) keys with values exceeding the threshold are included in the خروجی
• MMP receives a summary report that includes noisy values for keys that have contributing values above the set threshold. The report may also include keys that have no associated real user contributions and are purely noised.
• MMP uses the x_network_bit_mapping field in trigger registration to determine which ad tech corresponds to which key.
• MMP can then contact the appropriate serving ad tech to understand the values in the source key.

In summary, key discovery enables MMPs to obtain aggregation keys without knowing them in advance, and avoid processing a large volume of source keys at the expense of added noise.

Note: This feature is in the proposal stage, and not yet available for testing. Your feedback and comments are encouraged .

Daisy chain redirects

By providing multiple Attribution-Reporting-Redirect headers in a source or trigger registration HTTPS server-response, an ad tech can use the Attribution Reporting API to perform multiple source and trigger registrations with a single registration API call.

In the server-response, the ad tech can also include a single Location (302 redirect) header with a URL, which in turn leads to another registration, up to a set limit.

Both types of headers are optional and none can be provided if redirects are not needed. Either one or both types of headers may be provided. Source and trigger registration requests (including redirects) are retried in case of network failure. The number of retries per request is limited to a fixed number to avoid significant impact on the device.

Redirects are not accepted for registerWebSource and registerWebTrigger used by browsers. More details can be found in the Cross Web and App Implementation Guide .

View measurement data in attribution reports

The Attribution Reporting API enables the following types of reports, described in more detail later on this page:

• Event-level reports associate a particular attribution source (click or view) with limited bits of high-fidelity trigger data.
• Aggregatable reports aren't necessarily tied with a specific attribution source. These reports provide richer, higher-fidelity trigger data than event-level reports, but this data is only available in an aggregate form.

These two report types are complementary to each other and can be used simultaneously.

Event-level reports

After a trigger is attributed to an attribution source, an event-level report is generated and stored on the device until it can be sent back to each ad tech's postback URL during one of the time windows for sending reports , described in more detail later on این صفحه

Event-level reports are useful when very little information is needed about the trigger. Event-level trigger data is limited to 3 bits of trigger data for clicks—which means that a trigger can be assigned one of eight categories—and 1 bit for views. In addition, event-level reports don't support encoding of high-fidelity trigger-side data, such as a specific price or trigger time. Because attribution happens on device, there is no support for cross-device analytics in the event-level reports.

The event-level report contains data such as the following:

• Destination: Advertiser app package name or eTLD+1 where the trigger happened
• Attribution Source ID: The same attribution source ID that was used for registering an attribution source
• Trigger type: 1 or 3 bits of low-fidelity trigger data, depending on the type of attribution source

Privacy-preserving mechanisms applied to all reports

The following limits are applied after priorities regarding attribution sources and triggers are taken into consideration.

Limits on number of ad techs

There are limits on the number of ad techs that can register or receive reports from the API, with a current proposal of the following:

• 100 ad techs with attribution sources per {source app, destination app, 30 days, device}.
• 10 ad techs with attributed triggers per {source app, destination app, 30 days, device}.
• 20 ad techs can register a single attribution source or trigger (via Attribution-Reporting-Redirect )

Limits on number of unique destinations

These limits make it difficult for a set of ad techs to collude by querying a large number of apps to understand a given user's app usage behavior.

• Across all registered sources, across all ad techs, the API supports no more than 200 unique destinations, per source app, per minute.
• Across all registered sources, for a single ad tech, the API supports no more than 50 unique destinations, per source app, per minute. This limit prevents one ad tech from using up the entire budget from the previously mentioned rate limit.

Expired sources don't count towards the rate limits.

One reporting origin per source app per day

A given ad tech platform may only use one reporting origin to register sources on a publisher app, for a given device, on the same day. This rate limit prevents ad techs from using multiple reporting origins to access additional privacy budget.

Consider the following scenario, where a single ad tech wants to use multiple reporting origins to register sources on a publisher app, for a single device.

1. Ad tech A's reporting origin 1 registers a source on App B
2. 12 hours later, ad tech A's reporting origin 2 attempts to register a source on App B

The second source, for Ad tech A's reporting origin 2, would be rejected by the API. Ad tech A's reporting origin 2 wouldn't be able to successfully register a source on the same device on App B until the following day.

Cooldown and rate limits

To limit the amount of user identity leakage between a {source, destination} pair, the API throttles the amount of total information sent in a given time period for a user.

The current proposal is to limit each ad tech to 100 attributed triggers per {source app, destination app, 30 days, device}.

Number of unique destinations

The API limits the number of destinations that an ad tech can try to measure. The lower the limit, the harder it is for an ad tech to use the API to attempt to measure user browsing activity that isn't associated with ads being shown.

The current proposal is to limit each ad tech to 100 distinct destinations with non-expired sources per source app.

Privacy-preserving mechanisms applied to event-level reports

Limited fidelity of trigger data

The API provides 1 bit for view-through triggers and 3 bits for click-through triggers. Attribution sources continue to support the full 64 bits of metadata.

You should evaluate if and how to reduce the information expressed in triggers so they work with the limited number of bits available in event-level reports.

Framework for differential privacy noise

A goal of this API is to allow event-level measurement to satisfy local differential privacy requirements by using k-randomized responses to generate a noisy output for each source event.

Noise is applied on whether an attribution source event is reported truthfully. An attribution source is registered on the device with probability $ 1-p $ that the attribution source is registered as normal, and with probability $ p $ that the device randomly chooses among all possible output states of the API (including not reporting anything at all, or reporting multiple fake reports).

The k-randomized response is an algorithm that is epsilon differentially private if the following equation is satisfied:

\[ p = \frac{k}{k + e^ε - 1} \]

For low values of ε, the true output is protected by the k-randomized response mechanism. Exact noise parameters are works in progress and are subject to change based on feedback, with a current proposal of the following:

• p=0.24% for navigation sources
• p=0.00025% for event sources

Limits on available triggers (conversions)

There are limits on the number of triggers per attribution source, with a current proposal of the following:

• 1-2 triggers for ad view attribution sources (2 triggers only available in the case of post-install attribution)
• 3 triggers for click ad attribution sources

Note: This describes the default API behavior for the number of attributions per source using event-level reporting. With the introduction of flexible event-level reporting in October 2023, ad techs can now configure this dimension of their reporting based on what works best for their use case.

Specific time windows for sending reports (default behaviour)

Event-level reports for ad view attribution sources are sent 1 hour after the source expires. This expiry date can be configured, but it cannot be less than 1 day or more than 30 days. If two triggers are attributed to an ad view attribution source (via post-install attribution )), event-level reports can be sent at the reporting window intervals specified as follows.

Event-level reports for ad click attribution sources cannot be configured and are sent before or when the source expires, at specified points in time relative to when the source was registered. The time between the attribution source and expiry is split into multiple reporting windows. Each reporting window has a deadline (from the attribution source time). At the end of each reporting window, the device collects all the triggers that have occurred since the previous reporting window and sends a scheduled report. The API supports the following reporting windows:

• 2 days: The device collects all the triggers that occurred at most 2 days after the attribution source was registered. The report is sent 2 days and 1 hour after the attribution source is registered.
• 7 days: The device collects all the triggers that occurred more than 2 days but no more than 7 days after the attribution source was registered. The report is sent 7 days and 1 hour after the attribution source is registered.
• A custom length of time, defined by the "expiry" attribute of an attribution source. The report is sent 1 hour after the specified expiry time. This value cannot be less than 1 day or more than 30 days.

Note: This describes the default API behavior for event-level reporting windows. With the introduction of flexible event-level reporting in October 2023, ad techs can now configure this dimension of their reporting based on what works best for their use case.

Flexible event-level configuration

The default configuration for event level reporting is what ad techs are advised to start using as they begin utility testing, but may not be ideal for all use cases. The Attribution Reporting API will support optional, and more flexible configurations so that ad techs have increased control over the structure of their event level reports and are able to maximize the utility of the data.

This additional flexibility will be introduced into the Attribution Reporting API in two phases:

• Phase 1: Lite flexible event level configuration
  • This version provides a subset of the full features, and can be used independently of Phase 2.
• Phase 2: Full version of flexible event level configuration

Phase 1 (Lite flexible event level) could be used to:

• Vary the frequency of reports by specifying the number of reporting windows
• Vary the number of attributions per source registration
• Reduce the amount of total noise by decreasing the above parameters
• Configure reporting windows rather than using the defaults

Phase 2 (Full flexible event level) could be used to do all of the capabilities in Phase 1 and:

• Vary the trigger data cardinality in a report
• Reduce the amount of total noise by decreasing the trigger data cardinality

Reducing one dimension of the default configuration allows the ad tech to increase another dimension. Alternatively, the total amount of noise in an event level report may be reduced by net decreasing the parameters mentioned above.

In addition to dynamically setting noise levels based on an ad tech's chosen configuration, we will have some parameter limits to avoid large computation costs and configurations with too many output states (where noise will increase considerably). Here is an example set of restrictions. Feedback is encouraged on the [design proposal][50]:

• Maximum of 20 total reports, globally and per trigger_data
• Maximum of 5 possible reporting windows per trigger_data
• Maximum of 32 trigger data cardinality (not applicable for Phase 1: Lite Flexible Event Level)

As ad techs start using this feature, be advised that using extrema values may result in a large amount of noise, or failure to register if privacy levels are not met.

Note: Phase 1 (Lite flexible event level) was released in beta in October 2023. Phase 2 (Full flexible event level) is scheduled for release in beta later in Q1 2024.

Aggregatable reports

Before using aggregatable reports, you must set up your cloud account and start receiving aggregatable reports.

Aggregatable reports provide higher-fidelity trigger data from the device more quickly, beyond what is offered for event-level reports . This higher-fidelity data can only be learned in aggregate , and isn't associated with a particular trigger or user. Aggregation keys are up to 128 bits, and this allows aggregatable reports to support reporting use cases such as the following:

• Reports for trigger values, such as revenue
• Handling more trigger types

In addition, aggregatable reports use the same source-prioritized attribution logic as event-level reports, but they support more conversions attributed to a click or view.

The overall design of how the Attribution Reporting API prepares and sends aggregatable reports, shown in the diagram, is as follows:

1. The device sends encrypted aggregatable reports to the ad tech. In a production environment, ad techs can't use these reports directly.
2. The ad tech sends a batch of aggregatable reports to the aggregation service for aggregation.
3. The aggregation service reads a batch of aggregatable reports, decrypts and aggregates them.
4. The final aggregates are sent back to the ad tech in a summary report .

Process that the Attribution Reporting API uses to prepare and send aggregatable reports.

Aggregatable reports contain the following data related to attribution sources:

• Destination: The app's package name or eTLD+1 web URL where the trigger happened.
• Date: The date when the event represented by the attribution source occurred.
• Payload: Trigger values, collected as encrypted key/value pairs, which is used in the trusted aggregation service to compute aggregations.

Aggregation services

The following services provide data aggregation capabilities and safeguard against unauthorized access to aggregated data..

These services are managed by different parties, which are described in more detail later on this page:

• The aggregation service is the only one that ad techs are expected to deploy.
• The key management and aggregatable report accounting services are run by trusted parties called coordinators . These coordinators attest that the code running the aggregation service is the publicly-available code provided by Google and that all aggregation service users have the same key and aggregatable report accounting services applied to them.

Aggregation service

Ad tech platforms must, in advance, deploy an aggregation service that's based on binaries provided by Google.

This aggregation service operates in a Trusted Execution Environment (TEE) hosted in the cloud. A TEE offers the following security benefits:

• It ensures that the code operating in the TEE is the specific binary offered by Google. Unless this condition is satisfied, the aggregation service can't access the decryption keys it needs to operate.
• It offers security around the running process, isolating it from external monitoring or tampering.

These security benefits make it safer for an aggregation service to perform sensitive operations, such as accessing encrypted data.

For more information on the design, workflow, and security considerations of the aggregation service, see the aggregation service document on GitHub.

Key management service

This service verifies that an aggregation service is running an approved version of the binary and then provides the aggregation service in the ad tech with the correct decryption keys for their trigger data.

Aggregatable report accounting

This service tracks how often an ad tech's aggregation service accesses a specific trigger—which can contain multiple aggregation keys—and limits access to the appropriate number of decryptions. Refer to the Aggregation Service for the Attribution Reporting API design proposal for details.

Aggregatable Reports API

The API for creating contributions to aggregatable reports uses the same base API as when registering an attribution source for event-level reports. The following sections describe the extensions of the API.

Register the aggregatable source data

When the API makes a request to the Attribution Source URI, the ad tech can register a list of aggregation keys, named histogram_contributions , by responding with a new field called aggregation_keys in HTTP header Attribution-Reporting-Register-Source , with key as the key_name and value as key_piece :

• (Key) Key name: A string for the name of the key. Used as a join key to combine with trigger-side keys to form the final key.
• (Value) Key piece: A bitstring value for the key.

The final histogram bucket key is fully defined at trigger time by performing a binary OR operation on these pieces and the trigger-side pieces.

Final keys are restricted to a maximum of 128 bits; keys longer than this are truncated. This means that hex strings in the JSON should be limited to at most 32 digits.

Learn more about how aggregation keys are structured and how you can configure aggregation keys.

In the following example, an ad tech uses the API to collect the following:

• Aggregate conversion counts at a campaign level
• Aggregate purchase values at a geo level

// This is where the Attribution-Reporting-Register-Source object appears when
// an ad tech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Source:
…
aggregation_keys: {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).

  "campaignCounts": "0x159",
  // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue"
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
  "geoValue": "0x5"
}

Register the aggregatable trigger

Trigger registration includes two additional fields.

The first field is used to register a list of aggregate keys on the trigger side. The ad tech should respond back with the aggregatable_trigger_data field in HTTP header Attribution-Reporting-Register-Trigger , with the following fields for each aggregate key in the list:

• Key piece: A bitstring value for the key.
• Source keys: A list of strings with the names of attribution source side keys that the trigger key should be combined with to form the final keys.

The second field is used to register a list of values which should contribute to each key. The ad tech should respond back with the aggregatable_values field in the HTTP header Attribution-Reporting-Register-Trigger . The second field is used to register a list of values which should contribute to each key, which can be integers in the range $ [1, 2^{16}] $.

Each trigger can make multiple contributions to the aggregatable reports. The total amount of contributions to any given source event is bound by an $ L1 $ parameter, which is the maximum sum of contributions (values) across all aggregate keys for a given source. $ L1 $ refers to the L1 sensitivity or norm of the histogram contributions per source event. Exceeding these limits causes future contributions to silently drop. The initial proposal is to set $ L1 $ to $ 2^{16} $ (65536).

The noise in the aggregation service is scaled in proportion to this parameter. Given this, it is recommended to appropriately scale the values reported for a given aggregate key, based on the portion of $ L1 $ budget allocated to it. This approach helps ensure that the aggregate reports retain the highest possible fidelity when noise is applied. This mechanism is highly flexible and can support many aggregation strategies.

In the following example, the privacy budget is split equally between campaignCounts and geoValue by splitting the $ L1 $ contribution to each:

// This is where the Attribution-Reporting-Register-Trigger object appears
// when an ad tech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Trigger:{
    …
    "aggregatable_trigger_data":

    [
    // Each dictionary independently adds pieces to multiple source keys.
    {
    // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
    // A 9-bit offset is needed because there are 511 possible campaigns, which
    // will take up 9 bits in the resulting key.
        "key_piece": "0x400",// Conversion type purchase = 2
        // Apply this key piece to:
        "source_keys": ["campaignCounts"]
    },
    {
    // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
    // A 7-bit offset is needed because there are ~100 regions for the geo key,
    // which will take up 7 bits of space in the resulting key.
        "key_piece": "0xA80",
        // Apply this key piece to:
        "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
    }
    ]

    // Specify an amount of an abstract value which can be integers in [1, 2^16] to
    // contribute to each key that is attached to aggregation keys in the order that
    // they're generated.
    aggregatable_values:
    {
    // Privacy budget for each key is L1 / 2 = 2^15 (32768).
    // Conversion count was 1.
    // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
        "campaignCounts": 32768,

    // Purchase price was $52.
    // Purchase values for the app range from $1 to $1,024 (integers only).
    // Scaling factor applied is 32768 / 1024 = 32.
    // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
        "geoValue": 1664
    }
}

The preceding example generates the following histogram contributions:

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

Note: filters still apply to aggregatable reports, and each dictionary in aggregatable_trigger_data can still optionally have conversion filters applied to it, just like the trigger filters for event-level reports.

The scaling factors can be inverted in order to obtain the correct values, modulo noise that is applied:

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

حریم خصوصی متفاوت

A goal of this API is to have a framework which can support differentially private aggregate measurement. This can be achieved by adding noise proportional to the $ L1 $ budget, such as picking noise with the following distribution:

\[ Laplace(\frac{L1}{ε}) \]

Protected Audience API and Attribution Reporting API Integration

Cross-API integration across the Protected Audience and Attribution Reporting APIs enables adtechs to evaluate their attribution performance across various remarketing tactics in order to understand which types of audiences deliver the highest ROI.

Through this cross-API integration, adtechs can:

• Create a key-value map of URIs to be used for both 1) interaction reporting and 2) source registration.
• Include CustomAudience in their source-side key mapping for aggregate summary reporting (using the Attribution Reporting API).

When a user sees or clicks on an ad:

• The URL used to report those interactions using Protected Audience will also be used to register a view or click as an eligible source with the Attribution Reporting API.
• The ad tech may choose to pass CustomAudience (or other relevant contextual information about the ad such as ad placement or view duration) using that URL so this metadata can propagate down to summary reports when the ad tech is reviewing aggregate campaign performance.

For more information on how this is enabled within Protected Audience, see the relevant section of the Protected Audience API explainer .

Registration priority, attribution, and reporting examples

This example showcases a set of user interactions and how ad tech defined attribution source and trigger priorities could affect attributed reports. In this example, we assume the following:

• All attribution sources and triggers are registered by the same ad tech, for the same advertiser.
• All attribution sources and triggers are happening during the first event reporting window (within 2 days of initially displaying the ads in a publisher app).

Consider the case where a user does the following:

1. The user sees an ad. Ad tech registers an attribution source with the API, with a priority of 0 (view #1).
2. The user sees an ad, registered with a priority of 0 (view #2).
3. The user clicks an ad, registered with a priority of 1 (click #1).
4. The user converts (reaches landing page) in an advertiser app. The ad tech registers a trigger with the API, with a priority of 0 (conversion #1).
   • As triggers are registered, the API performs attribution first before generating reports.
   • There are 3 attribution sources available: view #1, view #2, and click #1. The API attributes this trigger to click #1 because it's the highest priority and most recent.
   • View #1 and view #2 are discarded and are no longer eligible for future attribution.
5. The user adds an item to their cart in the advertiser app, registered with a priority of 1 (conversion #2).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.
6. The user adds an item to their cart in the advertiser app, registered with a priority of 1 (conversion #3).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.
7. The user adds an item to their cart in the advertiser app, registered with a priority of 1 (conversion #4).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.
8. The user makes a purchase in the advertiser app, registered with a priority of 2 (conversion #5).
   • Click #1 is the only eligible attribution source. The API attributes this trigger to click #1.

Event-level reports have the following characteristics:

• By default, the first 3 triggers attributed to a click and the first trigger attributed to a view are sent out after applicable reporting windows.
• Within the reporting window, if there are triggers registered with higher priority, those take precedence and replace the most recent trigger.
• In the preceding example, the ad tech receives 3 event reports after the 2-day reporting window, for conversion #2, conversion #3, and conversion #5.
  • All 5 triggers are attributed to click #1. By default, the API would send out reports for the first 3 triggers: conversion #1, conversion #2, and conversion #3.
  • However, conversion #4's priority ( 1 ) is higher than conversion #1's priority ( 0 ). Conversion #4's event report replaces conversion #1's event report to be sent out.
  • Additionally, conversion #5's priority ( 2 ) is higher than any other trigger. Conversion #5's event report replaces conversion #4's report to be sent out.

Aggregatable reports have the following characteristics:

• Encrypted aggregatable reports are sent to the ad tech as soon as they are processed, a few hours after the triggers are registered.

  As an ad tech, you create their batches based on the information that comes unencrypted in your aggregatable reports. This information is contained in the shared_info field in your aggregatable report, and includes timestamp and reporting origin. You can't batch based on any encrypted information in your aggregation key-value pairs. Some simple strategies you can follow are batching reports daily or weekly. Ideally, batches should contain at least 100 reports each.

• It's up to the ad tech on when and how to batch the aggregatable reports and send to the aggregation service.

• Compared to event-level reports, encrypted aggregatable reports can attribute more triggers to a source.

• In the preceding example, 5 aggregatable reports are sent out, one for each registered trigger.

Transitional debugging reports

The Attribution Reporting API is a new and fairly complex way to do attribution measurement without cross-app identifiers. As such, we are supporting a transitional mechanism to learn more information about attribution reports when the advertising ID is available (the user has not opted out of personalization using the advertising ID and the publisher or advertiser app has declared AdID permissions) . This ensures that the API can be fully understood during roll-out, help flush out any bugs, and more easily compare the performance to advertising ID-based alternatives. There are two types of debugging reports: attribution-success and verbose.

Read the guide on transitional debugging reports for details on debugging reports with app-to-web and web-to-app measurement.

Attribution-success debugging reports

Source and trigger registrations both accept a new 64-bit debug_key field (formatted as a String), which the ad tech populates. source_debug_key and trigger_debug_key are passed unaltered in both event-level and aggregate reports.

If a report is created with both source and trigger debug keys, a duplicate debug report is sent with limited delay to a .well-known/attribution-reporting/debug/report-event-attribution endpoint. The debug reports are identical to normal reports, including both debug key fields. Including these keys in both allows tying normal reports to the separate stream of debug reports.

• For event-level reports:
  • Duplicate debug reports are sent with limited delay and therefore aren't suppressed by limits on available triggers , which allows ad tech to understand the impact of those limits for event-level reports.
  • Event-level reports associated with false trigger events will not have trigger_debug_key s. This allows ad tech to more closely understand how noise is applied in the API.
• For aggregatable reports:
  • We will support a new debug_cleartext_payload field which contains the decrypted payload, only if both source_debug_key and trigger_debug_key are set.

Verbose debugging reports

Verbose debugging reports allow developers to monitor certain failures in the attribution source or trigger registrations. These debugging reports are sent with limited delay after attribution source or trigger registrations to a . well-known/attribution-reporting/debug/verbose endpoint.

Each verbose report contains the following fields:

• Type : what caused the report to be generated. See the full list of verbose report types .
  • In general, there are source verbose reports and trigger verbose reports.
  • Source verbose reports require the advertising ID to be available to the publisher app, and trigger verbose reports require the advertising ID to be available to the advertiser app.
  • Trigger verbose reports (with the exception of trigger-no-matching-source ) can optionally include the source_debug_key . This can only be included if the advertising ID is also available to the publisher app.
• Body : The report's body, which depends on its type.

Ad techs need to opt in to receive verbose debugging reports using a new debug_reporting dictionary field in the Attribution-Reporting-Register_Source and Attribution-Reporting-Register-Trigger headers.

• Source verbose reports require opt-in on the source registration header only.
• Trigger debug reports require opt-in on the trigger registration header only.

How to use debug reports

If a conversion took place (according to your existing measurement system) and a debug report was received for that conversion, this means the trigger was successfully registered.

For each debug attribution report, check if you're receiving a regular attribution report that matches the two debug keys.

When there's no match, it can be for a number of reasons.

Works as intended:

• Privacy-preserving API behaviors:
  • A user hits the report rate limit—causing all subsequent reports to not be sent in the time period; or a source is removed due to the pending destination limit.
  • For event-level reports: the report is subject to randomized response (noise) and is suppressed, or you may receive a randomized report.
  • For event-level reports: the limit of three (for clicks) or one (for views) reports has been reached, and subsequent reports have no explicit priority set, or a priority that is lower than existing reports.
  • The contribution limits for aggregatable reports have been exceeded.
• Ad tech-defined business logic:
  • A trigger is filtered out via filters or priority rules.
• Time delays or interactions with network availability (eg, the user turns off their device for an extended period of time).

Unintended causes:

• Implementation issues:
  • The source header is misconfigured.
  • The trigger header is misconfigured.
  • Other configuration issues.
• Device or network issues:
  • Failures due to network conditions.
  • Source or trigger registration response doesn't reach the client.
  • API bug.

Future considerations & open questions

The Attribution Reporting API is a work in progress. We're also exploring future potential features, such as non-last-click attribution models and cross-device measurement use cases.

Additionally, we'd like to seek feedback from the community on a few issues:

1. Are there any use cases where you'd like the API to send out reports for the verified install? These reports would count against ad tech platforms' respective rate limits.
2. Do you foresee any difficulties with passing the InputEvent from the app to ad tech for source registration?
3. Do you have any special attribution use cases for pre-loaded apps or re-installed apps?