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

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

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

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

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

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

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

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

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

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

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