این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

تنظیم گزارش‌های اشکال‌زدایی برای گزارش‌های Attribution، تنظیم گزارش‌های اشکال‌زدایی برای گزارش Attribution

بخش 2 از 3 در مورد اشکال زدایی گزارش انتساب. گزارش های اشکال زدایی خود را تنظیم کنید.

واژه نامه

مبدا گزارش منبعی است که [ منبع گزارش 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: تأیید کنید که راه‌اندازی شما گزارش‌های اشکال زدایی مفصل ایجاد می‌کند

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

نکته کلیدی: گزارش اشکال زدایی مفصلی را انتخاب کنید که آزمایش آن ساده است. trigger-no-matching-source کاندیدای خوبی است، زیرا می توانید آن را با تبدیل ایجاد کنید. گزارش‌های پرمخاطب که به رویدادهای محرک مربوط می‌شوند، کاندیدای بهتری هستند. انواع گزارش پرمخاطب که به رویدادهای منبع مربوط می شوند، برای تولید هدفمند خسته کننده تر هستند.

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 )

تا بعدی

قسمت 3: اشکال زدایی کتاب آشپزی