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

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

מילון מונחים

  • המקור של הדיווח הוא המקור שמגדיר את הכותרות מקור וטריגר לדיווח השיוך. כל הדוחות שנוצרו על ידי הדפדפן נשלחים למקור הזה. בהנחיות האלה אנחנו משתמשים ב-https://adtech.example בתור מקור הדיווח לדוגמה.
  • דוח שיוך (Attribution) (דוח בקיצור) הוא הדוח הסופי (ברמת האירוע או באופן מצטבר) שמכיל את נתוני המדידה שביקשתם.
  • דוח ניפוי באגים מכיל נתונים נוספים על דוח השיוך (Attribution), או על מקור או אירוע מסוג טריגר. קבלת דוח על ניפוי באגים לא בהכרח מצביעה על כך שמשהו עובד בצורה לא תקינה. יש שני סוגים של דוחות ניפוי באגים
  • דוח ניפוי באגים בזמן ההעברה הוא דוח לניפוי באגים, שיש להגדיר קובץ cookie כדי ליצור ולשלוח אותו. אם לא הוגדר קובץ Cookie, ולאחר שקובצי Cookie של צד שלישי יצאו משימוש, דוחות ניפוי באגים במעבר לא יהיו זמינים. כל דוחות ניפוי הבאגים שמתוארים במדריך הזה הם דוחות ניפוי באגים בזמן מעבר.
  • דוחות ניפוי באגים בהצלחה עוקבים אחרי יצירה מוצלחת של דוח שיוך. הן קשורות ישירות לדוח השיוך. דוחות ניפוי הבאגים שהצליחו זמינים החל מגרסה 101 של Chrome (אפריל 2022).
  • דוחות Verbose לניפוי באגים יכולים לעקוב אחרי דוחות חסרים ולעזור לכם להבין למה הם חסרים. הם מציינים מקרים שבהם הדפדפן לא תיעד מקור או לא הפעיל אירוע (כלומר הוא לא יפיק דוח שיוך), ומקרים שבהם לא ניתן ליצור או לשלוח דוח שיוך מסיבה כלשהי. דוחות ניפוי באגים מילוליים כוללים שדה type שמתאר את הסיבה לכך שלא נוצרו אירוע מקור, אירוע הפעלה או דוח שיוך. דוחות Verbose לניפוי באגים זמינים החל מ-Chrome 109 (יציב בינואר 2023).
  • מפתחות לניפוי באגים הם מזהים ייחודיים שאפשר להגדיר גם בצד המקור וגם בצד הטריגר. מפתחות לניפוי באגים מאפשרים למפות המרות שמבוססות על קובצי cookie והמרות שמבוססות על שיוך. אחרי שמגדירים את המערכת ליצור דוחות ניפוי באגים ולהגדיר מפתחות לניפוי באגים, הדפדפן יכלול את המפתחות האלה לניפוי באגים בכל דוחות השיוך (Attribution) ובדוחות ניפוי הבאגים.

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

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

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

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

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

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

  • בודקים שהקוד שלכם מוגבל על ידי זיהוי התכונות. כדי לוודא שה-API לא חסום על ידי Permissions-Policy, מריצים את הקוד הבא:

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

    אם בדיקת זיהוי התכונה הזו מחזירה את הערך true, ה-API מותר בהקשר (בדף) שבו הבדיקה פועלת.

  • (לא נדרש בשלב הבדיקה: בודקים שהגדרתם Permissions-Policy)

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

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

יש סוגים שונים של בעיות בכלי הפיתוח. אם נתקלת בבעיה מסוג 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 יהיה קיים בשני הזמנים.

קוד הדגמה: debug cookie

שימו לב שאפשר להפעיל דוחות ניפוי באגים בדפדפנים במצב B, שבהם קובצי 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: מגדירים נקודת קצה לאיסוף דוחות ניפוי באגים של הצלחה

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

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