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

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

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

  • أصل إعداد التقارير هو المصدر الذي يضبط عنوانَي المصدر والعامل الخاص بإعداد تقارير تحديد المصدر. ويتم إرسال جميع التقارير التي ينشئها المتصفّح إلى هذا المصدر. في هذه الإرشادات، نستخدم https://adtech.example كمثال على مصدر الإبلاغ.
  • تقرير تحديد المصدر (التقرير باختصار) هو التقرير النهائي (على مستوى الحدث أو القابل للتجميع) الذي يحتوي على بيانات القياس التي طلبتها.
  • يحتوي تقرير تصحيح الأخطاء على بيانات إضافية عن تقرير تحديد المصدر أو عن مصدر أو حدث عامل تشغيل. لا يعني تلقّي تقرير تصحيح الأخطاء بالضرورة أنّ شيء ما يعمل بشكل غير صحيح. هناك نوعان من تقارير تصحيح الأخطاء.
  • تقرير تصحيح الأخطاء الانتقالي هو تقرير تصحيح أخطاء يتطلّب ضبط ملف تعريف الارتباط حتى يتم إنشاؤه وإرساله. لن تتوفّر تقارير تصحيح الأخطاء الانتقالية في حال عدم ضبط ملف تعريف ارتباط، وعند إيقاف ملفات تعريف الارتباط التابعة لجهات خارجية نهائيًا. إنّ جميع تقارير تصحيح الأخطاء الموضَّحة في هذا الدليل هي تقارير تصحيح أخطاء انتقالية.
  • تتتبّع تقارير تصحيح الأخطاء الناجحة إنشاء تقرير تحديد المصدر بنجاح. ترتبط ارتباطًا مباشرًا بتقرير تحديد المصدر. تتوفّر تقارير تصحيح الأخطاء الناجحة منذ إصدار Chrome 101 (نيسان/أبريل 2022).
  • بإمكان تقارير تصحيح الأخطاء المطوَّلة تتبُّع التقارير غير المتوفّرة ومساعدتك في تحديد سبب عدم توفّرها. وهي تشير إلى الحالات التي لم يسجِّل فيها المتصفّح مصدرًا أو أدّى إلى بدء حدث، ما يعني أنّه لن ينشئ تقرير تحديد مصدر)، والحالات التي يتعذّر فيها إنشاء تقرير تحديد المصدر أو إرساله لسببٍ ما. تتضمّن تقارير تصحيح الأخطاء المطوَّلة حقل type يصف سبب عدم إنشاء حدث مصدر أو حدث عامل تشغيل أو تقرير تحديد مصدر. تتوفّر تقارير تصحيح الأخطاء المطوَّلة اعتبارًا من الإصدار 109 من Chrome (استقرار في كانون الثاني/يناير 2023).
  • مفاتيح تصحيح الأخطاء هي معرّفات فريدة يمكنك ضبطها على كل من الجانب المصدر وجانب المشغّل. وتمكّنك مفاتيح تصحيح الأخطاء من ربط الإحالات الناجحة المستندة إلى ملفات تعريف الارتباط والإحالات الناجحة المستندة إلى الإحالة. عند إعداد نظامك لإنشاء تقارير تصحيح الأخطاء وإعداد مفاتيح تصحيح الأخطاء، سيضمِّن المتصفّح مفاتيح تصحيح الأخطاء هذه في جميع تقارير تحديد المصدر وتقارير تصحيح الأخطاء.

لمزيد من المفاهيم والمصطلحات الرئيسية المُستخدَمة في مستنداتنا، يُرجى الرجوع إلى مسرد مصطلحات "مبادرة حماية الخصوصية".

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

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

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

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

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

  • تأكَّد من أنّ رمزك مُقيّد بميزة رصد المحتوى. للتأكّد من أنّ واجهة برمجة التطبيقات لم يتم حظرها من خلال سياسة الأذونات، يمكنك تنفيذ الرمز البرمجي التالي:

    if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}

    إذا كانت نتيجة التحقّق من رصد الميزات هذه هي "صحيح"، يُسمح باستخدام واجهة برمجة التطبيقات في السياق (الصفحة) الذي يتم فيه إجراء التحقّق.

  • (غير مطلوب خلال مرحلة الاختبار: تأكَّد من ضبط سياسة الأذونات)

حلّ المشاكل الأساسية في الدمج

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

يمكن أن تكون مشاكل DevTools من أنواع مختلفة. إذا واجهت 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

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

الرمز التجريبي: debug cookie

يُرجى العِلم أنّه يمكن تفعيل تقارير تصحيح الأخطاء للمتصفّحات في الوضع ب، حيث يتم إيقاف ملفات تعريف الارتباط التابعة لجهات خارجية لتسهيل الاختبار والاستعداد لإيقاف ملفات تعريف الارتباط التابعة لجهات خارجية نهائيًا. بالنسبة إلى المتصفّحات في "الوضع ب"، لا تحتاج إلى ضبط ملف تعريف ارتباط تصحيح الأخطاء لتفعيل تقارير تصحيح الأخطاء. انتقِل إلى الخطوة 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

عند بدء عملية تحديد المصدر، سيرسل المتصفّح على الفور تقرير 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);
  }
);

الرمز التجريبي: تقارير تصحيح الأخطاء على مستوى الحدث endpoint

الرمز التجريبي: تقارير تصحيح الأخطاء القابلة للتجميع نقطة النهاية

الخطوة 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
}

الرمز التجريبي: source header

الرمز التجريبي: trigger header

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

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

https://adtech.example/.well-known/attribution-reporting/debug/verbose

عند إنشاء تقارير تصحيح أخطاء مفصّلة، أي عندما لا يكون المصدر أو العامل المشغِّل مسجَّلاً، سيرسل المتصفّح على الفور تقرير تصحيح أخطاء مفصّلاً من خلال طلب POST إلى هذه النهاية. قد يبدو رمز الخادم لمعالجة تقارير debugging المفصّلة الواردة على النحو التالي (هنا في نقطة نهاية عقدة):

// 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
السبب الذي أدّى إلى إنشاء التقرير للاطّلاع على جميع أنواع تقارير التفصيل المكثّف والإجراءات التي يجب اتّخاذها استنادًا إلى كل نوع، راجِع مرجع تقارير التفصيل المكثّف في الجزء 3: دليل معالجة الأخطاء.
Body
نص التقرير يعتمد ذلك على نوعه. راجِع مرجع تقارير الصعوبات المفصّلة في الجزء 3: دليل تصحيح أخطاء الصعوبات المفصّلة.

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

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

التالي

الجزء 3: دليل إزالة الأخطاء