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

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

واژه نامه

  • The reporting origin is the origin that sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use https://adtech.example as the example reporting origin.
  • An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
  • A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
  • A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
  • Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
  • Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a type field that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023).
  • Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.

For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.

سوالات اجرایی؟

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

برای تنظیم گزارش های اشکال زدایی آماده شوید

قبل از تنظیم گزارش های اشکال زدایی، این مراحل را دنبال کنید:

بررسی کنید که بهترین روش‌ها را برای یکپارچه‌سازی 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 مواجه شدید، سرصفحه را در ابزار اعتبارسنجی هدر کپی کنید. این به شما کمک می کند فیلدی را که مشکل ایجاد می کند شناسایی و برطرف کنید.

اعتبار سنجی سرصفحه های گزارش انتساب

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

برای شرکت در دریافت گزارش‌های اشکال‌زدایی، با report-header-errors به عنوان بخشی از سرصفحه پاسخ Attribution-Reporting-Info پاسخ دهید.

Attribution-Reporting-Info: report-header-errors

توجه داشته باشید که Attribution-Reporting-Info یک هدر ساختار یافته فرهنگ لغت Attribution-Reporting-Info است، بنابراین ارائه کلید report-header-errors منطقی به معنای یک مقدار واقعی است.

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

https://<reporting origin>/.well-known/attribution-reporting/debug/verbose

داده های گزارش در بدنه درخواست به عنوان یک لیست JSON از اشیاء دارای این فرم گنجانده شده است:

[{
  "type": "header-parsing-error",
  "body": {
    "context_site": "https://source.example",
    "header": "Attribution-Reporting-Register-Source",
    "value": "!!!", // header value received in the response
    "error": "invalid JSON" // optional error details that may vary across browsers or different versions of the same browser
  }
}]
اسکرین شات: ابزار اعتبارسنجی هدر

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

کوکی زیر را روی منبع گزارش تنظیم کنید:

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

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

  1. chrome://attribution-internals را در مرورگر خود باز کنید.
  2. یک منبع (تبدیل) را در سایت خود فعال کنید که با گزارش Attribution تنظیم شده است. با توجه به اینکه قبل از این تبدیل هیچ تعامل تبلیغاتی (نمایش یا کلیک) وجود نداشته است، باید انتظار داشته باشید که یک گزارش اشکال زدایی مفصل از نوع trigger-no-matching-source ایجاد شود.
  3. در chrome://attribution-internals ، برگه گزارش‌های اشکال‌زدایی Verbose را باز کنید و بررسی کنید که یک گزارش اشکال‌زدایی کامل از نوع trigger-no-matching-source ایجاد شده است.
  4. در سرور خود، بررسی کنید که نقطه پایانی شما بلافاصله این گزارش اشکال زدایی مفصل را دریافت کرده است.

مرحله 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: اشکال زدایی کتاب آشپزی