דף זה תורגם על ידי 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

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

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

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

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

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

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

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

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

נקודת קצה (endpoint) לדוחות ניפוי באגים מוצלחים ברמת האירוע: 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);
  }
);

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

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

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

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

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

שלב 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) כדי לאסוף את דוחות ניפוי הבאגים. נקודת הקצה (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);
  }
);

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

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

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

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

נקודה חשובה: כדאי לבחור דוח ניפוי באגים מפורט שקל לבדוק אותם. trigger-no-matching-source הוא מועמד טוב, כי אפשר ליצור אותו באמצעות המרה. דוחות מילוליים שקשורים להקפצת אירועים הם בדרך כלל מועמדים טובים יותר סוגי דוחות מפורטים קשורות לאירועי מקור מסובכים יותר ליצירה מכוונת.

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