بخش 2 از 3 در مورد اشکال زدایی گزارش انتساب. گزارش های اشکال زدایی خود را تنظیم کنید.
واژه نامه
- مبدا گزارش منبعی است که منبع گزارش Attribution و هدرهای راهانداز را تنظیم میکند. تمام گزارش های تولید شده توسط مرورگر به این مبدا ارسال می شود. در این راهنما،
https://adtech.example
به عنوان منبع گزارش نمونه استفاده می کنیم. - گزارش انتساب ( گزارش به اختصار) گزارش نهایی (در سطح رویداد یا جمعآوری) است که حاوی دادههای اندازهگیری درخواستی شما است.
- گزارش اشکالزدایی حاوی دادههای اضافی درباره یک گزارش انتساب، یا درباره یک منبع یا رویداد راهانداز است. دریافت گزارش اشکالزدایی لزوماً به این معنی نیست که چیزی درست کار نمیکند! دو نوع گزارش اشکال زدایی وجود دارد
- گزارش اشکال زدایی انتقالی یک گزارش اشکال زدایی است که برای تولید و ارسال به کوکی نیاز دارد. اگر کوکی تنظیم نشده باشد و پس از منسوخ شدن کوکیهای شخص ثالث، گزارشهای اشکالزدایی انتقالی در دسترس نخواهد بود. همه گزارش های اشکال زدایی که در این راهنما توضیح داده شده اند، گزارش های اشکال زدایی انتقالی هستند.
- گزارشهای اشکالزدایی موفقیتآمیز تولید موفقیتآمیز گزارش انتساب را دنبال میکنند. آنها مستقیماً به گزارش اسناد مربوط می شوند. گزارشهای اشکالزدایی موفقیت آمیز از Chrome 101 (آوریل 2022) در دسترس بوده است.
- گزارشهای اشکالزدایی کامل میتوانند گزارشهای مفقود را ردیابی کنند و به شما در تعیین علت گم شدن آنها کمک کنند. آنها مواردی را نشان میدهند که مرورگر یک منبع یا رویداد راهانداز را ثبت نکرده است (به این معنی که گزارش انتساب تولید نمیکند)، و مواردی که به دلایلی نمیتوان گزارش انتساب ایجاد یا ارسال کرد. گزارشهای اشکالزدایی کامل شامل یک فیلد
type
است که دلیل ایجاد نشدن رویداد منبع، رویداد راهانداز یا گزارش انتساب را توضیح میدهد. گزارشهای اشکالزدایی کامل از Chrome 109 در دسترس هستند ( در ژانویه 2023 پایدار است ). - کلیدهای اشکالزدایی شناسههای منحصربهفردی هستند که میتوانید هم در سمت منبع و هم در سمت ماشه تنظیم کنید. کلیدهای اشکالزدایی به شما امکان میدهند تا تبدیلهای مبتنی بر کوکی و تبدیلهای مبتنی بر اسناد را ترسیم کنید. هنگامی که سیستم خود را برای تولید گزارشهای اشکالزدایی و تنظیم کلیدهای اشکالزدایی تنظیم میکنید، مرورگر این کلیدهای اشکالزدایی را در همه گزارشهای انتساب و گزارشهای اشکالزدایی گنجانده است.
برای مفاهیم بیشتر و اصطلاحات کلیدی مورد استفاده در اسناد ما، به واژه نامه جعبه ایمنی حریم خصوصی مراجعه کنید.
،- مبدا گزارش منبعی است که منبع گزارش Attribution و هدرهای راهانداز را تنظیم میکند. تمام گزارش های تولید شده توسط مرورگر به این مبدا ارسال می شود. در این راهنما،
https://adtech.example
به عنوان منبع گزارش نمونه استفاده می کنیم. - گزارش انتساب ( گزارش به اختصار) گزارش نهایی (در سطح رویداد یا جمعآوری) است که حاوی دادههای اندازهگیری درخواستی شما است.
- گزارش اشکالزدایی حاوی دادههای اضافی درباره یک گزارش انتساب، یا درباره یک منبع یا رویداد راهانداز است. دریافت گزارش اشکالزدایی لزوماً به این معنی نیست که چیزی درست کار نمیکند! دو نوع گزارش اشکال زدایی وجود دارد
- گزارش اشکال زدایی انتقالی یک گزارش اشکال زدایی است که برای تولید و ارسال به کوکی نیاز دارد. اگر کوکی تنظیم نشده باشد و پس از منسوخ شدن کوکیهای شخص ثالث، گزارشهای اشکالزدایی انتقالی در دسترس نخواهد بود. همه گزارش های اشکال زدایی که در این راهنما توضیح داده شده اند، گزارش های اشکال زدایی انتقالی هستند.
- گزارشهای اشکالزدایی موفقیتآمیز تولید موفقیتآمیز گزارش انتساب را دنبال میکنند. آنها مستقیماً به گزارش اسناد مربوط می شوند. گزارشهای اشکالزدایی موفقیت آمیز از Chrome 101 (آوریل 2022) در دسترس بوده است.
- گزارشهای اشکالزدایی کامل میتوانند گزارشهای مفقود را ردیابی کنند و به شما در تعیین علت گم شدن آنها کمک کنند. آنها مواردی را نشان میدهند که مرورگر یک منبع یا رویداد راهانداز را ثبت نکرده است (به این معنی که گزارش انتساب تولید نمیکند)، و مواردی که به دلایلی نمیتوان گزارش انتساب ایجاد یا ارسال کرد. گزارشهای اشکالزدایی کامل شامل یک فیلد
type
است که دلیل ایجاد نشدن رویداد منبع، رویداد راهانداز یا گزارش انتساب را توضیح میدهد. گزارشهای اشکالزدایی کامل از Chrome 109 در دسترس هستند ( در ژانویه 2023 پایدار است ). - کلیدهای اشکالزدایی شناسههای منحصربهفردی هستند که میتوانید هم در سمت منبع و هم در سمت ماشه تنظیم کنید. کلیدهای اشکالزدایی به شما امکان میدهند تا تبدیلهای مبتنی بر کوکی و تبدیلهای مبتنی بر اسناد را ترسیم کنید. هنگامی که سیستم خود را برای تولید گزارشهای اشکالزدایی و تنظیم کلیدهای اشکالزدایی تنظیم میکنید، مرورگر این کلیدهای اشکالزدایی را در همه گزارشهای انتساب و گزارشهای اشکالزدایی گنجانده است.
برای مفاهیم بیشتر و اصطلاحات کلیدی مورد استفاده در اسناد ما، به واژه نامه جعبه ایمنی حریم خصوصی مراجعه کنید.
سوالات اجرایی؟
اگر هنگام تنظیم گزارشهای اشکالزدایی با مشکلی مواجه شدید، در مخزن پشتیبانی برنامهنویس ما مشکلی ایجاد کنید و ما به شما در عیبیابی کمک میکنیم.
برای تنظیم گزارش های اشکال زدایی آماده شوید
قبل از تنظیم گزارش های اشکال زدایی، این مراحل را دنبال کنید:
بررسی کنید که بهترین روشها را برای یکپارچهسازی API اعمال کردهاید
بررسی کنید که کد شما در پشت تشخیص ویژگی قرار دارد. برای اینکه مطمئن شوید API توسط Permissions-Policy مسدود نشده است، کد زیر را اجرا کنید:
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }
اگر این بررسی تشخیص ویژگی درست را برگرداند، API در زمینه (صفحه) جایی که بررسی اجرا می شود مجاز است.
(در مرحله آزمایش لازم نیست: بررسی کنید که یک Permissions-Policy تنظیم کرده اید)
مشکلات اساسی یکپارچه سازی را برطرف کنید
در حالی که گزارشهای اشکالزدایی برای کمک به شناسایی و تجزیه و تحلیل ضرر در مقیاس مفید هستند، برخی از مشکلات یکپارچهسازی را میتوان به صورت محلی شناسایی کرد. مشکلات پیکربندی نادرست سرصفحه منبع و راهانداز، مشکلات تجزیه JSON، زمینه ناامن (غیر HTTPS) و سایر مشکلاتی که مانع از عملکرد API میشوند، در برگه DevTools Issues ظاهر میشوند.
مشکلات DevTools می تواند انواع مختلفی داشته باشد. اگر با مشکل invalid header
مواجه شدید، سرصفحه را در ابزار اعتبارسنجی هدر کپی کنید. این به شما کمک می کند فیلدی را که مشکل ایجاد می کند شناسایی و برطرف کنید.
تنظیم گزارش های اشکال زدایی: مراحل مشترک برای گزارش های موفقیت و گزارش های پرمخاطب
کوکی زیر را روی منبع گزارش تنظیم کنید:
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
مرورگر وجود این کوکی را هم در ثبت منبع و هم در ثبت ماشه بررسی می کند. گزارش اشکال زدایی موفقیت آمیز تنها در صورتی ایجاد می شود که کوکی در هر دو زمان موجود باشد.
توجه داشته باشید که گزارشهای اشکالزدایی را میتوان برای مرورگرها در حالت B فعال کرد، جایی که کوکیهای شخص ثالث غیرفعال هستند تا آزمایش و آمادهسازی برای از بین رفتن کوکیهای شخص ثالث را تسهیل کنند. برای مرورگرهای حالت B، نیازی به تنظیم کوکی اشکال زدایی برای فعال کردن گزارش های اشکال زدایی ندارید. برای تنظیم کلیدهای اشکال زدایی برای گزارش های اشکال زدایی موفقیت آمیز، به مرحله 2 بروید.
مرحله 2: کلیدهای اشکال زدایی را تنظیم کنید
هر کلید اشکال زدایی باید یک عدد صحیح بدون علامت 64 بیتی باشد که به صورت رشته پایه 10 فرمت شده است. هر کلید اشکال زدایی را یک شناسه منحصر به فرد قرار دهید. گزارش اشکال زدایی موفقیت آمیز تنها در صورتی ایجاد می شود که کلیدهای اشکال زدایی تنظیم شده باشند.
- کلید اشکالزدایی سمت منبع را به اطلاعات اضافی در زمان منبع که فکر میکنید برای اشکالزدایی برای شما مرتبط است، ترسیم کنید.
- کلید اشکالزدایی سمت ماشه را به اطلاعات اضافی در زمان ماشه که فکر میکنید برای اشکالزدایی مرتبط است، ترسیم کنید.
برای مثال می توانید کلیدهای اشکال زدایی زیر را تنظیم کنید:
- شناسه کوکی + مهر زمان منبع به عنوان کلید اشکال زدایی منبع (و همان مهر زمانی را در سیستم مبتنی بر کوکی خود ثبت کنید)
- شناسه کوکی + مهر زمانی راهاندازی بهعنوان کلید اشکالزدایی راهانداز (و همان مهر زمانی را در سیستم مبتنی بر کوکیهای خود ثبت کنید)
با این کار، میتوانید از اطلاعات تبدیل مبتنی بر کوکی برای جستجوی گزارشهای اشکالزدایی یا گزارشهای اسناد مربوطه استفاده کنید. در قسمت 3: کتاب آشپزی بیشتر بیاموزید.
کلید اشکال زدایی سمت منبع را با source_event_id
متفاوت کنید، تا بتوانید گزارش های فردی را که دارای شناسه رویداد منبع یکسان هستند، متمایز کنید.
Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"647775351539539"
}
Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743"
}
کد نسخه ی نمایشی: کلید اشکال زدایی منبع کد آزمایشی: کلید اشکال زدایی را فعال کنید
گزارش های اشکال زدایی موفقیت را تنظیم کنید
کد مثال در این بخش، گزارشهای اشکالزدایی موفقیت را هم برای گزارشهای سطح رویداد و هم برای گزارشهای تجمیعپذیر تولید میکند. گزارشهای سطح رویداد و تجمیعپذیر از کلیدهای اشکالزدایی یکسان استفاده میکنند.
مرحله 3: یک نقطه پایانی برای جمع آوری گزارش های اشکال زدایی موفقیت آمیز تنظیم کنید
یک نقطه پایانی برای جمع آوری گزارش های اشکال زدایی تنظیم کنید. این نقطه پایانی باید شبیه به نقطه پایانی اصلی باشد، با یک رشته debug
اضافی در مسیر:
- نقطه پایانی برای گزارشهای اشکالزدایی موفقیت در سطح رویداد :
https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- نقطه پایانی برای گزارشهای اشکالزدایی موفقیت جمعآوریشده :
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- نقطه پایانی برای گزارشهای اشکالزدایی موفقیت جمعآوریشده :
هنگامی که یک انتساب فعال می شود، مرورگر بلافاصله یک گزارش اشکال زدایی را از طریق یک درخواست POST
به این نقطه پایانی ارسال می کند. کد سرور شما برای رسیدگی به گزارشهای اشکالزدایی موفقیتآمیز ورودی ممکن است به شکل زیر باشد (در اینجا در نقطه پایانی گره):
// Handle incoming event-Level Success Debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/report-event-attribution',
async (req, res) => {
// Debug report is in req.body
res.sendStatus(200);
}
);
// Handle incoming aggregatable Success Debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/report-aggregate-attribution',
async (req, res) => {
// Debug report is in req.body
res.sendStatus(200);
}
);
کد آزمایشی: نقطه پایانی اشکال زدایی در سطح رویداد را گزارش می دهد
کد آزمایشی: نقطه پایانی گزارش اشکال زدایی قابل جمع آوری
مرحله 4: تأیید کنید که راهاندازی شما گزارشهای اشکال زدایی موفقیت آمیز را ایجاد میکند
-
chrome://attribution-internals
در مرورگر خود باز کنید. - اطمینان حاصل کنید که چک باکس Show Debug Reports در هر دو برگه Event-Level Reports و Aggregatable Reports علامت زده شده باشد.
- سایتهایی را که Attribution Reporting را در آنها پیادهسازی کردهاید باز کنید. مراحلی را که برای تولید گزارش های انتساب استفاده می کنید تکمیل کنید. همین مراحل گزارش های اشکال زدایی موفقیت آمیز را ایجاد می کنند.
- در
chrome://attribution-internals
:- بررسی کنید که گزارش های انتساب به درستی ایجاد شده باشند.
- در برگه گزارشهای سطح رویداد و برگه گزارشهای جمعآوری ، بررسی کنید که گزارشهای اشکالزدایی موفقیتآمیز نیز تولید میشوند. آنها را در لیست با مسیر
debug
آبی رنگشان شناسایی کنید.
- در سرور خود، بررسی کنید که نقطه پایانی شما فوراً این گزارش های اشکال زدایی موفقیت را دریافت کند. حتماً گزارشهای اشکالزدایی موفقیت در سطح رویداد و جمعآوری را بررسی کنید.
مرحله 5: گزارش های اشکال زدایی موفقیت را مشاهده کنید
گزارش اشکال زدایی موفقیت آمیز با گزارش انتساب یکسان است و شامل کلیدهای اشکال زدایی سمت منبع و سمت ماشه است.
{
"attribution_destination": "https://advertiser.example",
"randomized_trigger_rate": 0.0000025,
"report_id": "7d76ef29-d59e-4954-9fff-d97a743b4715",
"source_debug_key": "647775351539539",
"source_event_id": "760938763735530",
"source_type": "event",
"trigger_data": "0",
"trigger_debug_key": "156477391437535"
}
{
"aggregation_service_payloads": [
{
"debug_cleartext_payload": "omRkYXRhgqJldmFsdWVEAACAAGZidWNrZXRQPPhnkD+7c+wm1RjAlowp3KJldmFsdWVEAAARMGZidWNrZXRQJFJl9DLxbnMm1RjAlowp3GlvcGVyYXRpb25paGlzdG9ncmFt",
"key_id": "d5f32b96-abd5-4ee5-ae23-26490d834012",
"payload": "0s9mYVIuznK4WRV/t7uHKquHPYCpAN9mZHsUGNiYd2G/9cg87Y0IjlmZkEtiJghMT7rmg3GtWVPWTJU5MvtScK3HK3qR2W8CVDmKRAhqqlz1kPZfdGUB4NsXGyVCy2UWapklE/r7pmRDDP48b4sQTyDMFExQGUTE56M/8WFVQ0qkc7UMoLI/uwh2KeIweQCEKTzw"
}
],
"shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"debug_mode\":\"enabled\",\"report_id\":\"4a04f0ff-91e7-4ef6-9fcc-07d000c20495\",\"reporting_origin\":\"https://adtech.example\",\"scheduled_report_time\":\"1669888617\",\"source_registration_time\":\"1669852800\",\"version\":\"0.1\"}",
"source_debug_key": "647775351539539",
"trigger_debug_key": "156477391437535"
}
گزارش های اشکال زدایی مفصل را تنظیم کنید
مرحله 3: اشکال زدایی کامل را در سرصفحه های منبع و ماشه انتخاب کنید
debug_reporting
را در Attribution-Reporting-Register-Source
و Attribution-Reporting-Register-Trigger
روی true
تنظیم کنید.
Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}
Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}
مرحله 4: یک نقطه پایانی برای جمعآوری گزارشهای اشکال زدایی پرمخاطب تنظیم کنید
یک نقطه پایانی برای جمع آوری گزارش های اشکال زدایی تنظیم کنید. این نقطه پایانی باید شبیه به نقطه پایانی انتساب اصلی باشد، با یک رشته debug/verbose
اضافی در مسیر:
https://adtech.example/.well-known/attribution-reporting/debug/verbose
هنگامی که گزارشهای اشکالزدایی کامل ایجاد میشوند، یعنی زمانی که منبع یا راهاندازی ثبت نشده است، مرورگر بلافاصله یک گزارش اشکالزدایی کامل را از طریق یک درخواست POST
به این نقطه پایانی ارسال میکند. کد سرور شما برای رسیدگی به گزارش های اشکال زدایی پرمخاطب ورودی ممکن است به شکل زیر باشد (در اینجا در نقطه پایانی گره):
// Handle incoming verbose debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/verbose',
async (req, res) => {
// List of verbose debug reports is in req.body
res.sendStatus(200);
}
);
برخلاف گزارش های اشکال زدایی موفقیت آمیز، تنها یک نقطه پایانی برای گزارش های پرمخاطب وجود دارد. گزارشهای پرمخاطب که به گزارشهای سطح رویداد و گزارشهای انبوه مربوط میشوند، همگی به یک نقطه پایانی ارسال میشوند.
کد نسخه ی نمایشی: نقطه پایانی اشکال زدایی مفصل را گزارش می کند
مرحله 5: تأیید کنید که راهاندازی شما گزارشهای اشکال زدایی مفصل ایجاد میکند
در حالی که انواع مختلفی از گزارشهای عیبزدایی کامل وجود دارد، کافی است تنظیمات اشکالزدایی کامل خود را تنها با یک نوع گزارش اشکالزدایی کامل بررسی کنید. اگر این یک نوع گزارش اشکال زدایی پرمخاطب به درستی تولید و دریافت شود، به این معنی است که همه انواع گزارشهای اشکال زدایی کامل به درستی تولید و دریافت خواهند شد، زیرا همه گزارشهای اشکالزدایی کامل از پیکربندی یکسانی استفاده میکنند و به یک نقطه پایانی ارسال میشوند.
-
chrome://attribution-internals
در مرورگر خود باز کنید. - یک منبع (تبدیل) را در سایت خود راه اندازی کنید که با گزارش Attribution تنظیم شده است. با توجه به اینکه قبل از این تبدیل هیچ تعامل تبلیغاتی (نمایش یا کلیک) وجود نداشته است، باید انتظار داشته باشید که یک گزارش اشکال زدایی مفصل از نوع
trigger-no-matching-source
ایجاد شود. - در
chrome://attribution-internals
، برگه گزارشهای اشکالزدایی Verbose را باز کنید و بررسی کنید که یک گزارش اشکالزدایی کامل از نوعtrigger-no-matching-source
ایجاد شده است. - در سرور خود، بررسی کنید که نقطه پایانی شما بلافاصله این گزارش اشکال زدایی مفصل را دریافت کرده است.
مرحله 6: گزارش های اشکال زدایی مفصل را مشاهده کنید
گزارشهای اشکالزدایی پرمخاطب که در زمان راهاندازی ایجاد میشوند، شامل کلید اشکالزدایی سمت منبع و سمت ماشه میشوند (اگر منبع منطبقی برای ماشه وجود داشته باشد). گزارشهای اشکالزدایی کامل که در زمان منبع تولید میشوند شامل کلید اشکالزدایی سمت منبع است.
مثالی از یک درخواست حاوی گزارشهای اشکالزدایی کامل، ارسال شده توسط مرورگر:
[
{
"body": {
"attribution_destination": "http://arapi-advertiser.localhost",
"randomized_trigger_rate": 0.0000025,
"report_id": "92b7f4fd-b157-4925-999e-aad6361de759",
"source_debug_key": "282273499788483",
"source_event_id": "480041649210491",
"source_type": "event",
"trigger_data": "1",
"trigger_debug_key": "282273499788483"
},
"type": "trigger-event-low-priority"
},
{
"body": {
"attribution_destination": "http://arapi-advertiser.localhost",
"limit": "65536",
"source_debug_key": "282273499788483",
"source_event_id": "480041649210491",
"source_site": "http://arapi-publisher.localhost",
"trigger_debug_key": "282273499788483"
},
"type": "trigger-aggregate-insufficient-budget"
}
]
هر گزارش کامل حاوی فیلدهای زیر است:
-
Type
- چه چیزی باعث ایجاد گزارش شده است. برای آشنایی با انواع گزارشهای پرمخاطب و اقداماتی که باید بسته به هر نوع انجام دهید، مرجع گزارشهای پرمخاطب در قسمت 3: کتاب آشپزی اشکالزدایی را مرور کنید.
-
Body
- بدنه گزارش بستگی به نوع آن خواهد داشت. مرجع گزارش های پرمخاطب را در قسمت 3: کتاب آشپزی اشکال زدایی مرور کنید.
بدنه یک درخواست حداقل شامل یک و حداکثر دو گزارش مفصل خواهد بود:
- اگر شکست فقط بر گزارشهای سطح رویداد تأثیر میگذارد (یا اگر فقط بر گزارشهای جمعآوریشده تأثیر میگذارد، یک گزارش پرمخاطب). عدم موفقیت ثبت منبع یا ماشه تنها یک دلیل دارد. از این رو می توان یک گزارش پرمخاطب برای هر شکست و هر نوع گزارش (در سطح رویداد یا جمع آوری) ایجاد کرد.
- اگر شکست بر گزارشهای سطح رویداد و گزارشهای انبوه تأثیر بگذارد، دو گزارش پرمخاطب - با یک استثنا: اگر دلیل شکست برای گزارشهای سطح رویداد و گزارشهای انباشته یکسان باشد، فقط یک گزارش پرمخاطب تولید میشود (مثال:
trigger-no-matching-source
)