تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إعداد تقارير تصحيح الأخطاء لإعداد تقارير الإحالة

الجزء 2 من 3 أجزاء حول تصحيح أخطاء تقارير تحديد المصدر أعِدّ تقارير تصحيح الأخطاء.

مسرد المصطلحات

报告来源是用于设置归因报告来源和触发器标头的来源。浏览器生成的所有报告都会发送到此源。在本指南中，我们使用 https://adtech.example 作为示例报告来源。
归因报告（简称“报告”）是包含您请求的衡量数据的最终报告（事件级报告或可汇总报告）。
调试报告包含有关归因报告或者来源或触发器事件的其他数据。收到调试报告并不一定表示存在问题！调试报告有两种
过渡调试报告是一种调试报告，需要设置 Cookie 才能生成和发送。如果 Cookie 未设置且第三方 Cookie 被弃用，过渡调试报告将不可用。本指南中描述的所有调试报告都是过渡性调试报告。
成功调试报告用于跟踪成功生成归因报告。它们与归因报告直接相关。从 Chrome 101（2022 年 4 月）开始，已提供成功调试报告。
详细调试报告可以跟踪缺失的报告，并帮助您确定缺失报告的原因。它们分别用于表明浏览器未记录来源或触发器事件（这意味着浏览器不会生成归因报告）以及由于某种原因无法生成或发送归因报告的情况。详细调试报告包含一个 type 字段，用于说明未生成来源事件、触发器事件或归因报告的原因。从 Chrome 109（2023 年 1 月稳定版）开始提供详细调试报告。
调试键是您可以在来源端和触发器端设置的唯一标识符。通过调试键，您可以映射基于 Cookie 的转化和基于归因的转化。将系统设置为生成调试报告并设置调试密钥后，浏览器会将这些调试密钥添加到所有归因报告和调试报告中。

如需了解我们的文档中使用的更多概念和关键术语，请参阅 Privacy Sandbox 术语表。

هل لديك أسئلة حول التنفيذ؟

إذا واجهت أي مشكلة أثناء إعداد تقارير تصحيح الأخطاء، يمكنك إنشاء مشكلة في ملف التجميع الخاص بدعم المطوّرين، وسنساعدك في تحديد المشاكل وحلّها.

الاستعداد لإعداد تقارير تصحيح الأخطاء

قبل إعداد تقارير تصحيح الأخطاء، اتّبِع الخطوات التالية:

التحقّق من تطبيق أفضل الممارسات لدمج واجهة برمجة التطبيقات

تأكَّد من أنّ رمزك مُقيّد بميزة رصد المحتوى. للتأكد من عدم حظر واجهة برمجة التطبيقات بواسطة Permissions-Policy، شغِّل الرمز التالي:
```
if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}
```
إذا كانت نتيجة التحقّق من رصد الميزات هذه هي "صحيح"، يُسمح باستخدام واجهة برمجة التطبيقات في السياق (الصفحة) الذي يتم فيه إجراء التحقّق.
(لا يُشترط ذلك خلال مرحلة الاختبار: تأكَّد من ضبط سياسة الأذونات)

إصلاح المشاكل الأساسية في عملية الدمج

على الرغم من أنّ تقارير تصحيح الأخطاء مفيدة لمساعدتك في رصد الخسارة وتحليلها على نطاق واسع، يمكن رصد بعض مشاكل الدمج على الجهاز. ستظهر في علامة التبويب المشاكل في "أدوات المطوّر" مشاكل الإعداد الخاطئ لعنوان المصدر والتشغيل، ومشاكل تحليل تنسيق JSON، والسياق غير الآمن (غير HTTPS)، وغيرها من المشاكل التي تمنع واجهة برمجة التطبيقات من العمل.

قد تختلف أنواع المشاكل في أدوات مطوّري البرامج. إذا واجهت مشكلة invalid header، انسخ العنوان إلى أداة التحقّق من صحة العناوين. سيساعدك ذلك في تحديد الحقل الذي يتسبب في حدوث مشكلة وحلّها.

التحقّق من صحة عناوين تقارير تحديد المصدر

يمكنك استخدام أداة التحقّق من صحة العنوان للتحقّق من صحة العناوين المرتبطة بواجهة برمجة التطبيقات Attribution Reporting 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

سيتحقق المتصفح من توفُّر ملف تعريف الارتباط هذا في كل من تسجيل المصدر والتشغيل. ولن يتم إنشاء تقرير تصحيح الأخطاء بنجاح إلا إذا كان ملف تعريف الارتباط متوفرًا في كلتا الحالتين.

الترميز التجريبي: ملف تعريف الارتباط لتصحيح الأخطاء

تجدر الإشارة إلى أنّه يمكن تفعيل تقارير تصحيح الأخطاء للمتصفّحات في الوضع (ب)، حيث يتم إيقاف ملفات تعريف الارتباط التابعة لجهات خارجية لتسهيل اختبار ملفات تعريف الارتباط التابعة لجهات خارجية والتحضير لها. بالنسبة إلى المتصفّحات في "الوضع ب"، لا تحتاج إلى ضبط ملف تعريف ارتباط تصحيح الأخطاء لتفعيل تقارير تصحيح الأخطاء. انتقِل إلى الخطوة 2 لإعداد مفاتيح تصحيح الأخطاء لتقارير تصحيح الأخطاء الناجحة.

الخطوة 2: ضبط مفاتيح تصحيح الأخطاء

يجب أن يكون كل مفتاح تصحيح أخطاء عددًا صحيحًا غير موقَّت بسعة 64 بت بتنسيق سلسلة ثنائية عشرية. اجعل كل مفتاح تصحيح أخطاء معرِّفًا فريدًا. لن يتم إنشاء تقرير تصحيح أخطاء النجاح إلا في حال ضبط مفاتيح تصحيح الأخطاء.

اربط مفتاح تصحيح الأخطاء من جهة المصدر بمعلومات إضافية في وقت المصدر تعتقد أنّها ذات صلة بتصحيح الأخطاء.
يمكنك ربط مفتاح تصحيح الأخطاء من جهة العامل المشغِّل بمعلومات إضافية في وقت التفعيل تعتقد أنّها مفيدة لتصحيح الأخطاء.

يمكنك على سبيل المثال ضبط مفاتيح تصحيح الأخطاء التالية:

رقم تعريف ملف تعريف الارتباط + الطابع الزمني للمصدر كمفتاح تصحيح أخطاء المصدر (وتسجيل الطابع الزمني نفسه في نظامك المستنِد إلى ملفات تعريف الارتباط)
رقم تعريف ملف تعريف الارتباط + الطابع الزمني للتشغيل كمفتاح تصحيح أخطاء التشغيل (وتسجيل الطابع الزمني نفسه في نظامك المستنِد إلى ملفات تعريف الارتباط)

وبالتالي، يمكنك استخدام معلومات الإحالات الناجحة المستندة إلى ملفات تعريف الارتباط للاطّلاع على تقارير تصحيح الأخطاء أو تقارير تحديد المصدر المقابلة. تعرَّف على مزيد من المعلومات في الجزء 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"
}

Demo code: مفتاح تصحيح أخطاء المصدر الرمز التوضيحي: مفتاح تصحيح الأخطاء

إعداد تقارير تصحيح أخطاء النجاح

يُنشئ مثال الرمز البرمجي في هذا القسم تقارير تصحيح أخطاء النجاح لكلٍّ من التقارير على مستوى الحدث والتقارير القابلة للتجميع. تستخدِم التقارير على مستوى الحدث والقابلة للتجميع مفاتيح تصحيح الأخطاء نفسها.

الخطوة 3: إعداد نقطة نهاية لجمع تقارير تصحيح أخطاء حالات النجاح

عليك إعداد نقطة نهاية لجمع تقارير تصحيح الأخطاء. يجب أن تكون نقطة النهاية هذه مشابهة لنقطة نهاية تحديد المصدر الرئيسية، مع سلسلة debug إضافية في المسار:

نقطة نهاية تقارير تصحيح أخطاء النجاح على مستوى الحدث: https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- نقطة نهاية تقارير تصحيح أخطاء النجاح المجمّعة: https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution

عند بدء عملية تحديد المصدر، سيرسل المتصفّح على الفور تقرير debugging عبر طلب 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 في المتصفّح.
تأكَّد من وضع علامة في مربّع الاختيار عرض تقارير تصحيح الأخطاء في كلّ من علامتَي التبويب التقارير على مستوى الحدث والتقارير القابلة للتجميع.
افتح المواقع الإلكترونية التي نفّذت فيها ميزة "تقارير الإحالة". أكمِل الخطوات التي تستخدمها لإنشاء تقارير تحديد المصدر، وستؤدي هذه الخطوات نفسها إلى إنشاء تقارير تصحيح أخطاء النجاح.
في 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 على true في كل من Attribution-Reporting-Register-Source وAttribution-Reporting-Register-Trigger.

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);
  }
);

على عكس تقارير تصحيح أخطاء حالات النجاح، تتوفّر نقطة نهاية واحدة فقط للتقارير المفصّلة. سيتم إرسال كل التقارير المفصّلة ذات الصلة بالتقارير على مستوى الحدث والتقارير المجمّعة إلى نقطة النهاية نفسها.

الرمز التجريبي: تقارير تصحيح الأخطاء المفصّلة endpoint

الخطوة 5: التأكّد من أنّ عملية الإعداد ستؤدي إلى إنشاء تقارير تصحيح أخطاء مفصّلة

على الرغم من توفّر أنواع متعدّدة من تقارير تصحيح الأخطاء التفصيلية، يكفي التحقّق من إعدادات تصحيح الأخطاء التفصيلية باستخدام نوع واحد فقط من تقارير تصحيح الأخطاء التفاصيلية. إذا تم إنشاء نوع واحد من تقارير تصحيح الأخطاء التفصيلية بشكلٍ صحيح وتلقّيه بشكلٍ صحيح، يعني ذلك أنّه سيتم أيضًا إنشاء جميع أنواع تقارير تصحيح الأخطاء التفصيلية بشكلٍ صحيح وتلقّيها بشكلٍ صحيح، لأنّ جميع تقارير تصحيح الأخطاء التفصيلية تستخدِم الإعدادات نفسها ويتم إرسالها إلى نقطة النهاية نفسها.

نقطة رئيسية: اختَر تقرير تصحيح أخطاء مطوَّل يسهل اختباره. يُعد trigger-no-matching-source من الفلاتر الجيدة، لأنه يمكنك إنشاؤه عن طريق التحويل. إنّ التقارير المفصّلة التي تتعلّق بأحداث التفعيل تكون عادةً مرشّحين أفضل، وأنواع التقارير المفصّلة التي تتعلّق بأحداث المصدر تكون أكثر تعقيدًا في إنشائها عن قصد.

افتح chrome://attribution-internals في المتصفّح.
تشغيل إحالة (إحالة ناجحة) على موقعك الإلكتروني تم إعدادها باستخدام "تقارير تحديد المصدر" وبما أنّه لم يكن هناك تفاعل مع الإعلان (مرّة ظهور أو نقرة) قبل هذه الإحالة الناجحة، من المتوقّع أن يتم إنشاء تقرير تصحيح أخطاء مطوَّل من النوع trigger-no-matching-source.
في chrome://attribution-internals، افتح علامة التبويب تقارير تصحيح الأخطاء المفصّلة وتأكّد من أنّه تم إنشاء تقرير تصحيح أخطاء مفصّل من النوع 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: السبب الذي أدّى إلى إنشاء التقرير للتعرّف على جميع أنواع التقارير المطوَّلة والإجراءات التي يجب اتّخاذها استنادًا إلى كل نوع، يمكنك مراجعة مرجع التقارير المطوَّلة في الجزء الثالث: تصحيح الأخطاء في كتاب الطبخ.
Body: نص التقرير: سيعتمد ذلك على نوعه. راجِع مرجع تقارير الصعوبات المفصّلة في الجزء 3: دليل تصحيح أخطاء الصعوبات المفصّلة.

سيحتوي نص الطلب على تقرير واحد على الأقل أو تقريرَين مطوَّلَين على الأكثر:

تقرير مفصّل واحد إذا كان العُطل يؤثر فقط في التقارير على مستوى الحدث (أو إذا كان يؤثر فقط في التقارير القابلة للتجميع) هناك سبب واحد فقط لتعذُّر تسجيل المصدر أو المشغِّل، وبالتالي يمكن إنشاء تقرير مطوّل واحد لكل نوع من أنواع التقارير ولكل نوع من أنواع التقارير (على مستوى الحدث أو قابل للتجميع).
تقريران مفصّلان إذا كان العُطل يؤثر في كلّ من التقارير على مستوى الحدث والتقارير القابلة للتجميع، مع استثناء: إذا كان سبب العُطل هو نفسه للتقارير على مستوى الحدث والتقارير القابلة للتجميع، يتم إنشاء تقرير مفصّل واحد فقط (مثال: trigger-no-matching-source)

الجزء 3: كتاب الطبخ لتصحيح الأخطاء