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

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

מילון מונחים

  • המקור של הדיווח הוא המקור שמגדיר את הכותרות מקור וטריגר לדיווח השיוך. כל הדוחות שנוצרו על ידי הדפדפן נשלחים למקור הזה. בהנחיות האלה אנחנו משתמשים ב-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 לפעול, יופיעו בכרטיסייה בעיות בכלי פיתוח.

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

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

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