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

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

מילון מונחים

  • The reporting origin is the origin that sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use https://adtech.example as the example reporting origin.
  • An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
  • A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
  • A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
  • Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
  • Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a type field that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023).
  • Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.

For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.

יש לך שאלות לגבי הטמעה?

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

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

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

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