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

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

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

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

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

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

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

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

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

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

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

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

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

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

צריך להגדיר נקודת קצה (endpoint) כדי לאסוף את דוחות ניפוי הבאגים. נקודת הקצה הזו צריכה להיות דומה לנקודת הקצה הראשית של השיוך (Attribution), עם מחרוזת debug נוספת בנתיב:

נקודת קצה (endpoint) לדוחות של ניפוי באגים שהושלמו ברמת האירוע: https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- נקודת קצה (endpoint) לדוחות נצברים של ניפוי באגים להצלחה: 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);
  }
);

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

קוד הדגמה: נקודת קצה (endpoint) של דוחות ניפוי באגים נצברים

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

פותחים את chrome://attribution-internals בדפדפן.
מוודאים שתיבת הסימון Show Debug Reports מסומנת בכרטיסייה דוחות ברמת האירוע ובכרטיסייה דוחות נצברים.
פותחים את האתרים שבהם הטמעתם את דיווח השיוך. מבצעים את השלבים ליצירת דוחות שיוך (Attribution). אותם שלבים ייצרו דוחות לניפוי באגים בהצלחה.
באמצעות chrome://attribution-internals:
- יש לוודא שדוחות השיוך נוצרו כראוי.
- בכרטיסייה דוחות ברמת האירוע ובכרטיסייה דוחות נצברים, בדקו שנוצרו גם דוחות לניפוי באגים שהצליחו. מזהים אותם ברשימה באמצעות הנתיב debug הכחול.

צילום מסך: נתונים פנימיים של Attribution

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

שלב 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
}

קוד הדגמה: כותרת המקור

קוד הדגמה: כותרת טריגר

שלב 4: מגדירים נקודת קצה (endpoint) כדי לאסוף דוחות מפורטים של ניפוי באגים

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

שלב 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: ניפוי באגים בספר המתכונים