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

الجزء 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.

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

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

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

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

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

  • تأكَّد من أنّ رمزك مُقيّد بميزة رصد المحتوى. للتأكد من عدم حظر واجهة برمجة التطبيقات بواسطة 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: التأكّد من أنّ عملية الإعداد ستؤدي إلى إنشاء تقارير تصحيح أخطاء مفصّلة

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

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

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

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

التالي

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