گزارش اسناد: نمای کلی سیستم

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

Attribution Reporting API به فناوران و تبلیغ‌کنندگان این امکان را می‌دهد تا اندازه‌گیری کنند که کلیک یا مشاهده آگهی منجر به تبدیل، مانند خرید، می‌شود. این API به ترکیبی از ادغام سمت مشتری و سمت سرور، بسته به نیازهای کسب و کار شما، متکی است.

قبل از ادامه، حتماً نمای کلی Attribution Reporting را بخوانید. این به شما کمک می کند تا هدف API و جریان گزارش های خروجی مختلف ( گزارش در سطح رویداد و گزارش های خلاصه ) را درک کنید. اگر با اصطلاحات ناآشنا مواجه شدید، به واژه نامه Privacy Sandbox مراجعه کنید.

این مقاله برای چه کسانی است؟

شما باید این مقاله را بخوانید اگر:

• شما یک فناوری تبلیغات یا تصمیم گیرنده فنی تبلیغ هستید. شما ممکن است در عملیات، DevOps، علم داده، فناوری اطلاعات، بازاریابی یا نقش دیگری که در آن تصمیمات اجرایی فنی می گیرید، کار کنید. شما تعجب می کنید که چگونه API ها برای اندازه گیری حفظ حریم خصوصی کار می کنند.
• شما یک متخصص فنی (مانند یک توسعه‌دهنده، اپراتور سیستم، معمار سیستم یا دانشمند داده) هستید که آزمایش‌هایی را با این محیط API و Aggregation Service راه‌اندازی می‌کنید.

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

بررسی اجمالی

Attribution Reporting API از خدمات بسیاری تشکیل شده است که نیاز به راه‌اندازی خاص، پیکربندی‌های سمت مشتری و استقرار سرور دارند. برای تعیین آنچه نیاز دارید، ابتدا:

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

همیشه دو (و گاهی اوقات سه) جزء وجود دارد که برای پشتیبانی از گزارش با هم کار می کنند:

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

اگر گزارش‌های جمع‌آوری‌شده را جمع‌آوری کرده‌اید، به جزء سوم نیاز دارید:

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

تصمیمات طراحی

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

گزارش خروجی می تواند:

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

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

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

هنگامی که تصمیم گرفتید چه چیزی را می‌خواهید اندازه بگیرید، می‌توانید سمت مشتری را برای Attribution Reporting API تنظیم کنید.

ارتباط وب سایت با مرورگر

توجه: زمانی که این API در حال آزمایش است، کد شما باید تأیید کند که API در دسترس است و Permissions-Policy مناسب را تنظیم کنید.

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

جریان رویداد اسناد

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

1. در سایت ناشر، یک عنصر تبلیغ (برچسب <a> یا <img> ) با یک ویژگی خاص attributionsrc پیکربندی شده است. مقدار آن یک URL است، برای مثال https://adtech.example/register-source/ad_id=... .

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

   <a href="https://shoes.example/landing" 
     attributionsrc="http://adtech.example/register-source?..."
     target="_blank">
   Click me</a>
   

   در اینجا نمونه ای از تصویری است که هنگام مشاهده باعث ثبت منبع می شود:

   <img href="https://advertiser.example/landing" 
     attributionsrc="https://adtech.example/register-source?..."/>
   

   از طرف دیگر، به جای عناصر HTML، می توان از فراخوانی های جاوا اسکریپت استفاده کرد.

   در اینجا یک مثال جاوا اسکریپت با استفاده از window.open() آورده شده است. توجه داشته باشید که برای جلوگیری از مشکلات مربوط به کاراکترهای خاص، URL با url رمزگذاری شده است.

   const encodedUrl = encodeURIComponent(
     'https://adtech.example/attribution_source?ad_id=...');
   window.open(
     "https://shoes.example/landing",
     "_blank",
     attributionsrc=${encodedUrl});
   

1. وقتی کاربر روی تبلیغ کلیک می‌کند یا آن را مشاهده می‌کند، مرورگر یک درخواست GET به attributionsrc می‌فرستد - معمولاً یک تبلیغ‌کننده یا نقطه پایانی ارائه‌دهنده فناوری تبلیغات.

2. پس از دریافت این درخواست، تبلیغ‌کننده یا ارائه‌دهنده فناوری تبلیغات تصمیم می‌گیرد به مرورگر دستور دهد رویدادهای منبع را برای تعامل با آگهی ثبت کند تا بعداً تبدیل‌ها به این آگهی نسبت داده شود. برای انجام این کار، تبلیغ‌کننده یا ارائه‌دهنده فناوری تبلیغاتی در پاسخ خود یک هدر HTTP ویژه را شامل می‌شود. این داده‌های سفارشی به این سرصفحه متصل می‌شود که اطلاعاتی درباره رویداد منبع (کلیک یا مشاهده آگهی) ارائه می‌کند—اگر تبدیلی برای این آگهی انجام شود، این داده‌های سفارشی در نهایت در گزارش انتساب ظاهر می‌شوند.

   

3. بعداً کاربر از سایت تبلیغ کننده بازدید می کند.

4. در هر صفحه مربوطه از سایت تبلیغ‌کننده - برای مثال، یک صفحه تأیید خرید یا یک صفحه محصول - یک پیکسل تبدیل ( عنصر <img> ) یا تماس جاوا اسکریپت درخواستی به https://adtech.example/conversion?param1=...&param2=... می‌کند. https://adtech.example/conversion?param1=...&param2=... .

5. سرویس در این URL - معمولاً تبلیغ‌کننده یا ارائه‌دهنده فناوری تبلیغاتی - درخواست را دریافت می‌کند. تصمیم می‌گیرد این را به عنوان تبدیل طبقه‌بندی کند، بنابراین باید به مرورگر دستور دهد که یک تبدیل را ثبت کند - یعنی یک منبع را راه‌اندازی کند . برای انجام این کار، تبلیغ‌کننده یا ارائه‌دهنده فناوری تبلیغات در پاسخ خود به درخواست پیکسل، یک هدر HTTP ویژه را شامل می‌شود که شامل داده‌های سفارشی درباره تبدیل است.

6. مرورگر - در دستگاه محلی کاربر - این پاسخ را دریافت می‌کند و داده‌های تبدیل را با رویداد منبع اصلی (کلیک یا مشاهده آگهی) مطابقت می‌دهد. در منابع Match to triggerها بیشتر بیاموزید

7. مرورگر گزارشی را برای ارسال به attributionsrc برنامه ریزی می کند. این گزارش شامل:

   1. داده‌های پیکربندی ارجاع سفارشی که ارائه‌دهنده فناوری تبلیغات یا تبلیغ‌کننده به رویداد منبع در مرحله 3 پیوست کرده است.
   2. مجموعه داده های تبدیل سفارشی در مرحله 6.

   

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

محرک های ارجاع (وب سایت تبلیغ کننده)

عامل انتساب رویدادی است که به مرورگر می‌گوید تبدیل‌ها را ثبت کند.

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

این اطمینان حاصل می کند که نتایج کلی برای این رویدادها دقیق و دقیق هستند.

منابع را با محرک‌ها مطابقت دهید

هنگامی که یک مرورگر یک پاسخ راه‌انداز انتساب دریافت می‌کند، مرورگر به فضای ذخیره‌سازی محلی دسترسی پیدا می‌کند تا منبعی را بیابد که هم با مبدأ راه‌انداز انتساب و هم با eTLD+1 آن URL صفحه مطابقت داشته باشد.

برای مثال، وقتی مرورگر یک راه‌انداز انتساب از adtech.example در shoes.example/shoes123 دریافت می‌کند، مرورگر به دنبال منبعی در فضای ذخیره‌سازی محلی می‌گردد که هم با adtech.example و هم shoes.example مطابقت داشته باشد.

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

اگر چندین منبع انتساب در حافظه محلی یافت شود، مرورگر منبعی را انتخاب می کند که اخیراً ذخیره شده است. در برخی موارد که منابع انتساب اولویت دارند، مرورگر منبعی را با بالاترین اولویت انتخاب می کند.

جمع آوری داده ها

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

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

گزارش‌های سطح رویداد بین 2 تا 30 روز تاخیر دارند. گزارش‌های جمع‌آوری‌شده با تأخیر تصادفی در عرض یک ساعت ارسال می‌شوند و رویدادها باید در حد بودجه مشارکت باشند. این انتخاب ها از حریم خصوصی محافظت می کنند و از سوء استفاده از اقدامات هر کاربر جلوگیری می کنند.

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

تولید گزارش خلاصه

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

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

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

گزارش های جمع آوری دسته ای

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

دسته ها باید حاوی گزارش های زیادی باشند تا اطمینان حاصل شود که نسبت سیگنال به نویز بالا است.

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

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

سرویس تجمع

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

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

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

بعدش چی؟

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

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

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

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

می‌توانید آزمایش کنید و در مکالمه‌ای درباره Attribution Reporting API شرکت کنید .