דף זה תורגם על ידי Cloud Translation API.

הגדרה של דוחות ניפוי באגים עבור דוחות שיוך (Attribution)

חלק 2 מתוך 3 בנושא ניפוי באגים בדיווח על שיוך (Attribution). מגדירים את דוחות ניפוי הבאגים.

מילון מונחים

报告来源是用于设置归因报告来源和触发器标头的来源。浏览器生成的所有报告都会发送到此源。在本指南中，我们使用 https://adtech.example 作为示例报告来源。
归因报告（简称“报告”）是包含您请求的衡量数据的最终报告（事件级报告或可汇总报告）。
调试报告包含有关归因报告或者来源或触发器事件的其他数据。收到调试报告并不一定表示存在问题！调试报告有两种
过渡调试报告是一种调试报告，需要设置 Cookie 才能生成和发送。如果 Cookie 未设置且第三方 Cookie 被弃用，过渡调试报告将不可用。本指南中描述的所有调试报告都是过渡性调试报告。
成功调试报告用于跟踪成功生成归因报告。它们与归因报告直接相关。从 Chrome 101（2022 年 4 月）开始，已提供成功调试报告。
详细调试报告可以跟踪缺失的报告，并帮助您确定缺失报告的原因。它们分别用于表明浏览器未记录来源或触发器事件（这意味着浏览器不会生成归因报告）以及由于某种原因无法生成或发送归因报告的情况。详细调试报告包含一个 type 字段，用于说明未生成来源事件、触发器事件或归因报告的原因。从 Chrome 109（2023 年 1 月稳定版）开始提供详细调试报告。
调试键是您可以在来源端和触发器端设置的唯一标识符。通过调试键，您可以映射基于 Cookie 的转化和基于归因的转化。将系统设置为生成调试报告并设置调试密钥后，浏览器会将这些调试密钥添加到所有归因报告和调试报告中。

如需了解我们的文档中使用的更多概念和关键术语，请参阅 Privacy Sandbox 术语表。

יש לכם שאלות בנושא הטמעה?

אם תיתקלו בבעיה במהלך הגדרת דוחות ניפוי הבאגים, תוכלו ליצור דיווח בספריית התמיכה למפתחים ואנחנו נעזור לכם לפתור את הבעיה.

הכנה להגדרת דוחות ניפוי באגים

לפני שמגדירים דוחות ניפוי באגים, צריך לבצע את השלבים הבאים:

מוודאים שהשתמשתם בשיטות המומלצות לשילוב API

לבדוק שהקוד מוגן מאחורי זיהוי תכונות. כדי לוודא שה-API לא חסום על ידי Permissions-Policy, מריצים את הקוד הבא:
```
if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}
```
אם הבדיקה של זיהוי התכונה מחזירה את הערך True, ה-API מותר בהקשר (בדף) שבו הבדיקה פועלת.
(לא נדרשת במהלך שלב הבדיקה: יש לוודא שהגדרתם את Permissions-Policy)

פתרון בעיות שילוב בסיסיות

דוחות ניפוי באגים עוזרים לזהות ולנתח אובדן בקנה מידה רחב, אבל אפשר לזהות בעיות מסוימות בשילוב באופן מקומי. בעיות בהגדרה שגויה של כותרות וטריגרים, בעיות בניתוח JSON, הקשר לא מאובטח (לא HTTPS) ובעיות אחרות שמונעות מה-API לפעול, יופיעו בכרטיסייה בעיות בכלי פיתוח.

יש סוגים שונים של בעיות בכלי הפיתוח. אם נתקלים בבעיה ב-invalid header, מעתיקים את הכותרת לכלי לאימות כותרות. כך תוכלו לזהות ולתקן את השדה שגורם לבעיה.

אימות כותרות של דוחות שיוך (Attribution)

אפשר להשתמש בכלי לאימות כותרות כדי לאמת את הכותרות שקשורות ל-Attribution Reporting API. תוכלו לעקוב אחר שגיאות אימות שמקורן בדפדפן כדי להקל על ניפוי הבאגים ב-API.

כדי להביע הסכמה לקבלת דוחות ניפוי באגים, צריך להשיב עם הערך report-header-errors כחלק מכותרת התגובה Attribution-Reporting-Info.

Attribution-Reporting-Info: report-header-errors

חשוב לשים לב ש-Attribution-Reporting-Info הוא כותרת מובנית של מילוןAttribution-Reporting-Info, ולכן ציון המפתח הבוליאני report-header-errors מרמז ערך True.

דוחות ניפוי באגים נשלחים באופן מיידי לנקודת הקצה לדיווח:

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
  }
}]

הגדרה של דוחות ניפוי באגים: שלבים נפוצים בדוחות הצלחה ובדוחות מפורטים

מגדירים את קובץ ה-cookie הבא במקור הדיווח:

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

הדפדפן יבדוק אם קובץ ה-cookie הזה קיים גם ברישום המקור וגם ברישום הטריגר. דוח ניפוי הבאגים שהצליח ייווצר רק אם קובץ ה-cookie נמצא בשני המקרים.

קוד הדגמה: קובץ cookie לניפוי באגים

שימו לב שאפשר להפעיל דוחות ניפוי באגים בדפדפנים במצב ב', שבהם קובצי Cookie של צד שלישי מושבתים, כדי להקל על הבדיקה וההכנה לקראת ההוצאה משימוש של קובצי Cookie של צד שלישי. בדפדפנים במצב B, אין צורך להגדיר את קובץ ה-cookie לניפוי באגים כדי להפעיל דוחות ניפוי באגים. תוכלו לדלג לשלב 2 כדי להגדיר מפתחות ניפוי באגים לדוחות ניפוי באגים מוצלחים.

שלב 2: הגדרת מפתחות לניפוי באגים

כל מפתח ניפוי באגים חייב להיות מספר שלם ללא סימן באורך 64 ביט בפורמט של מחרוזת בסיס 10. לכל מפתח ניפוי באגים צריך להיות מזהה ייחודי. הדוח על תוצאות ניפוי הבאגים ייווצר רק אם יוגדרו מפתחות ניפוי באגים.

ממפים את מפתח ניפוי הבאגים בצד המקור למידע נוסף בזמן המקור שלדעתכם רלוונטי לניפוי הבאגים.
ממפים את מפתח ניפוי הבאגים בצד הטריגר למידע נוסף בזמן הטריגר שלדעתכם רלוונטי לניפוי הבאגים.

לדוגמה, אפשר להגדיר את מפתחות ניפוי הבאגים הבאים:

מזהה קובץ cookie + חותמת זמן של המקור כמפתח ניפוי באגים של המקור (ותיעוד של אותה חותמת זמן במערכת שמבוססת על קובצי cookie)
מזהה קובץ ה-Cookie + חותמת הזמן של הטריגר כמפתח לניפוי באגים בטריגר (ותיעוד של אותה חותמת זמן במערכת שמבוססת על קובצי Cookie)

כך תוכלו להשתמש בנתוני המרות שמבוססים על קובצי cookie כדי לחפש את דוחות ניפוי הבאגים או דוחות השיוך המתאימים. מידע נוסף זמין בחלק 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: מגדירים נקודת קצה (endpoint) כדי לאסוף דוחות על תוצאות ניפוי הבאגים

מגדירים נקודת קצה כדי לאסוף את דוחות ניפוי הבאגים. נקודת הקצה הזו אמורה להיות דומה לנקודת הקצה הראשית לזיהוי השיוך, עם מחרוזת 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 בדפדפן.
מוודאים שהתיבה Show Debug Reports (הצגת דוחות ניפוי באגים) מסומנת גם בכרטיסייה Event-Level Reports (דוחות ברמת האירוע) וגם בכרטיסייה Aggregatable Reports (דוחות שניתן לצבור).
פותחים את האתרים שבהם הטמעתם את דוחות השיוך. מבצעים את השלבים ליצירת דוחות שיוך (Attribution). אותם השלבים יוצרים גם דוחות ניפוי באגים של הצלחה.
ב-chrome://attribution-internals:
- בודקים שהדוחות של השיוך (Attribution) נוצרים בצורה נכונה.
- בכרטיסייה דוחות ברמת האירוע ובכרטיסייה Aggregatable Reports, חשוב לוודא שנוצרים גם דוחות ניפוי באגים יעילים. מזהים אותם ברשימה עם הנתיב הכחול 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: מגדירים נקודת קצה לאיסוף דוחות ניפוי באגים מפורטים

מגדירים נקודת קצה כדי לאסוף את דוחות ניפוי הבאגים. נקודת הקצה (endpoint) הזו צריכה להיות דומה לנקודת הקצה הראשית של השיוך, עם מחרוזת 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 בדפדפן.
מפעילים באתר שיוך (המרה) שמוגדר באמצעות 'דיווח שיוך (Attribution)'. מכיוון שלא הייתה אינטראקציה עם המודעה (חשיפת מודעה או קליק) לפני ההמרה הזו, צפוי להיווצר דוח ניפוי באגים מפורט מסוג trigger-no-matching-source.
ב-chrome://attribution-internals, פותחים את הכרטיסייה Verbose debug reports ובודקים שנוצר דוח ניפוי באגים מפורט מסוג trigger-no-matching-source.
מוודאים שנקודת הקצה (endpoint) קיבלה מיד את דוח ניפוי הבאגים המפורט הזה בשרת.

שלב 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: מדריך לניפוי באגים