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

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

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

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

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

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

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

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

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

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

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

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

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

  • (لا يُشترط ذلك خلال مرحلة الاختبار: تأكَّد من أنّك ضبطت Permissions-Policy)

حلّ المشاكل الأساسية المتعلّقة بالتكامل

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

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

التحقّق من صحة عناوين Attribution Reporting

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

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

رمز العرض التوضيحي: مصدر العنوان

رمز العرض التوضيحي: trigger header

الخطوة 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 Reporting. بما أنّه لم يحدث أي تفاعل مع الإعلان (ظهور أو نقرة) قبل هذه الإحالة الناجحة، من المفترض أن يتم إنشاء تقرير تصحيح أخطاء مفصّل من النوع 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: دليل تصحيح الأخطاء