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

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

الجزء 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
}
```
في حال عرض نتيجة التحقّق من رصد الميزات على القيمة "صحيح"، سيتم السماح باستخدام واجهة برمجة التطبيقات في السياق (الصفحة) حيث يتم إجراء عملية التحقق.
(إجراء غير مطلوب أثناء مرحلة الاختبار: تحقق من أنك قمت بتعيين Permissions-Policy)

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

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

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

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

اضبط ملف تعريف الارتباط التالي على مصدر إعداد التقارير:

Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly

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

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

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

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

يجب أن يكون كل مفتاح تصحيح أخطاء عددًا صحيحًا غير موقَّع بحجم 64 بت بتنسيق كسلسلة base-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 في المتصفّح.
تأكّد من وضع علامة في مربّع الاختيار عرض تقارير تصحيح الأخطاء، في كلٍ من التقارير على مستوى الحدث وعلامات التبويب التقارير القابلة للتجميع.
افتح المواقع الإلكترونية التي أنشأت عليها "تقارير تحديد المصدر". مكتمل الخطوات التي تستخدمها لإنشاء تقارير تحديد المصدر؛ نفس هذه الخطوات سوف إنشاء تقارير تصحيح أخطاء النجاح.
في 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);
  }
);

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

الشفرة التجريبية: تقارير تصحيح الأخطاء المطوّلة نقطة النهاية

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

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

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

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