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

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

אימות של כותרות Attribution Reporting

אתם יכולים להשתמש בכלי לאימות כותרות כדי לאמת כותרות שקשורות ל-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

שימו לב שאפשר להפעיל דוחות ניפוי באגים עבור דפדפנים במצב ב', שבו קובצי Cookie של צד שלישי מושבתים כדי לאפשר בדיקה והכנה להוצאה משימוש של קובצי Cookie של צד שלישי. בדפדפנים במצב ב', לא צריך להגדיר את קובץ ה-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 Reporting. מבצעים את השלבים שמשמשים ליצירת דוחות שיוך. אותם שלבים ישמשו ליצירת דוחות ניפוי באגים של הצלחה.
  • ב-chrome://attribution-internals:
    • בודקים שדוחות השיוך נוצרים בצורה נכונה.
    • בכרטיסייה Event-Level Reports (דוחות ברמת האירוע) ובכרטיסייה Aggregatable Reports (דוחות מצטברים), בודקים שנוצרו גם דוחות ניפוי הבאגים של ההצלחה. אפשר לזהות אותם ברשימה לפי הנתיב הכחול debug שלהם.
פרטים פנימיים על שיוך (Attribution)
היבטים פנימיים של שיוך
  • בשרת, מוודאים שנקודת הקצה מקבלת באופן מיידי את דוחות הניפוי באגים האלה של הצלחה. חשוב לבדוק את דוחות הניפוי באגים של ההצלחה ברמת האירוע וברמה הניתנת לצבירה.
דיווח של יומני שרת מקורי
Reporting origin server logs

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

דוח ניפוי באגים של המרות מוצלחות זהה לדוח שיוך (Attribution), והוא מכיל את מפתחות ניפוי הבאגים בצד המקור ובצד הטריגר.

{
  "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
}

קוד הדגמה: source header

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