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

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

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

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

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

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

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

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

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

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

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

تحقق من أن الرمز الخاص بك محمي من خلال ميزة اكتشاف الميزات. للتأكد من عدم حظر واجهة برمجة التطبيقات بواسطة سياسة الأذونات، شغِّل الرمز التالي:
```
if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}
```
في حال عرض عملية التحقّق من رصد الميزات هذه على "صحيح"، يتم السماح بواجهة برمجة التطبيقات في السياق (الصفحة) الذي يتم فيه إجراء عملية التحقّق.
(إجراء غير مطلوب أثناء مرحلة الاختبار: التحقّق من إعداد سياسة أذونات)

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

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

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

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

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

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

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

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

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