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

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

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

מילון מונחים

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