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

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

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

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

این سند برای کیست؟

شما باید این سند را بخوانید اگر:

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

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

نمای کلی

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

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

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

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

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

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

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

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

گزارش خروجی می‌تواند به صورت زیر باشد:

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

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

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

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

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

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

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

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-encoded است تا از بروز مشکلات مربوط به کاراکترهای خاص جلوگیری شود.

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

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

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

   

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

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

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

7. مرورگر - در دستگاه محلی کاربر - این پاسخ را دریافت می‌کند و داده‌های تبدیل را با رویداد منبع اصلی (کلیک یا مشاهده تبلیغ) مطابقت می‌دهد.

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

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

   

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

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

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

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

این امر تأیید می‌کند که نتایج کلی برای این رویدادها دقیق و جزئی هستند.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

خدمات تجمیع

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

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

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

بعدش چی؟

ما می‌خواهیم با شما وارد گفتگو شویم تا مطمئن شویم API ای می‌سازیم که برای همه کار می‌کند.

بحث در مورد API

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

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

شما می‌توانید در گفتگوهای مربوط به API گزارش‌دهی انتساب ، شرکت کنید و آن را آزمایش کنید .