מעבר ל-Reporting API גרסה 1

יש גרסה חדשה של Reporting API. הוא פרטי יותר, ויש סיכוי גבוה יותר שתהיה תמיכה בו בדפדפנים שונים.

Maud Nalpas

Reporting API מעדכן אתכם על שגיאות שמתרחשות באתר בזמן שהמבקרים משתמשים בו. בעזרת הכלי תוכלו לראות התערבויות בדפדפן, קריסות בדפדפן, הפרות של מדיניות אבטחת התוכן (CSP), הפרות של COOP/COEP, אזהרות על הוצאה משימוש ועוד.

יש גרסה חדשה של Reporting API. ה-API החדש פשוט יותר, וסביר יותר שהוא יהיה נתמך בדפדפנים שונים.

סיכום

מפתחי אתרים

אם כבר יש לכם פונקציונליות של דיווח באתר: מעבירים לגרסה 1 באמצעות הכותרת החדשה (Reporting-Endpoints), אבל משאירים את הכותרת הקודמת למשך זמן מה (Report-To). אפשר לעיין במאמר העברה: קוד לדוגמה.

אם אתם מוסיפים פונקציונליות של דיווח לאתר עכשיו: השתמשו רק בכותרת החדשה (Reporting-Endpoints).

⚠️ בשני המקרים, חשוב להגדיר את הכותרת Reporting-Endpoints בכל התשובות שעשויות ליצור דוחות.

מפתחי שירותי דיווח

אם אתם מנהלים שירות של נקודת קצה או מפעילים שירות כזה, צפו לעלייה בנפח התנועה כשאתם או מפתחים חיצוניים תעברו ל-Reporting API v1 (כותרת Reporting-Endpoints).

בהמשך מופיעים פרטים וקוד לדוגמה.

רישום שגיאות ברשת ביומן

יתפתח מנגנון חדש לרישום ביומן של שגיאות רשת. כשהמנגנון החדש יהיה זמין, תוכלו לעבור מ-Reporting API v0 למנגנון החדש.

הדגמה וקוד

• אתר הדגמה: Reporting API חדש (גרסה 1)
• קוד לאתר ההדגמה

ההבדלים בין גרסה 0 לגרסה 1

מה עומד להשתנות

• ממשק ה-API שונה.

 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

• היקף הדוח שונה.

• שני ממשקי ה-API תומכים באותם סוגי דוחות, מלבד חריג אחד: בגרסה 1 אין תמיכה בדוחות של שגיאות ברשת. מידע נוסף זמין בשלבי ההעברה.
• אין תמיכה בגרסה 0 ולא תהיה תמיכה בה בדפדפנים שונים. סביר יותר שתהיה תמיכה בגרסה 1 במספר דפדפנים בעתיד.

מה לא משתנה

• הפורמט והמבנה של הדוחות לא השתנו.
• הבקשה שנשלחת מהדפדפן לנקודת הקצה נשארת בקשת POST של Content-type application/reports+json.
• אפשר למפות נקודות קצה מסוימות לסוגים מסוימים של דוחות גם בגרסה v0 וגם בגרסה v1.
• התפקיד של נקודת הקצה default לא השתנה.

• ל-Reporting API v1 אין השפעה על ReportingObserver. ל-ReportingObserver תמשיך להיות גישה לכל הדוחות שניתנים לצפייה, והפורמט שלהם יהיה זהה.

כל ההבדלים בין גרסה 0 לגרסה 1

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

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

הסיבה לכך היא שדוחות לא מקובצים ב-Reporting API v1 כמו שהם מקובצים ב-Reporting API v0. לכן, כשמפתחי האפליקציות יתחילו לעבור ל-Reporting API v1, מספר הדוחות יישאר דומה, אבל נפח הבקשות לשרת נקודת הקצה יגדל.

מפתחי אפליקציות: העברה אל Reporting-Endpoints (v1)

מה עליך לעשות?

יש כמה יתרונות לשימוש ב-Reporting API החדש (גרסה 1): ✅

• האותות מהדפדפנים חיוביים, כלומר צפויה תמיכה בדפדפנים שונים בגרסה 1 (בניגוד לגרסה 0 שנתמכת רק ב-Chrome וב-Edge).
• ממשק ה-API מצומצם יותר.
• אנחנו מפתחים כלים שקשורים ל-Reporting API החדש (גרסה 1).

לכן:

• אם באתר שלכם כבר נעשה שימוש ב-Reporting API v0 עם הכותרת Report-To, עליכם לעבור ל-Reporting API v1 (ראו שלבי ההעברה). אם באתר שלכם כבר מופעלת פונקציונליות של דיווח על הפרות של Content-Security-Policy, כדאי לעיין בשלביו הספציפיים של ההעברה לדיווח על CSP.
• אם עדיין לא השתמשתם ב-Reporting API באתר שלכם ואתם מוסיפים עכשיו פונקציונליות של דיווח: צריך להשתמש ב-Reporting API החדש (גרסה 1) (כותרת Reporting-Endpoints). יש חריג אחד: אם אתם צריכים להשתמש ביומן שגיאות ברשת, צריך להשתמש ב-Report-To (v0). כרגע אין תמיכה בדיווח ביומן על שגיאות ברשת ב-Reporting API v1. אנחנו נגבש מנגנון חדש לרישום שגיאות ברשת ביומן⏤עד שהוא יהיה זמין, תוכלו להשתמש ב-Reporting API v0. אם אתם צריכים רישום ביומן של שגיאות ברשת יחד עם סוגים אחרים של דוחות, צריך להשתמש גם ב-Report-To (v0) וגם ב-Reporting-Endpoints (v1). v0 מאפשר לכם לקבל רישום ביומן של שגיאות ברשת, ו-v1 מאפשר לכם לקבל דוחות של כל הסוגים האחרים.

שלבי ההעברה

המטרה שלכם בהעברה הזו היא לא לאבד דוחות שהייתם מקבלים בגרסה 0.

1. שלב 1 (עכשיו): משתמשים בשני הכותרות: Report-To (v0) ו-Reporting-Endpoints (v1).

   כך תוכלו:

   • דוחות מלקוחות חדשים יותר של Chrome ו-Edge, בזכות Reporting-Endpoints (v1).
   • דוחות מלקוחות ישנים יותר של Chrome ו-Edge, בזכות Report-To (v0).

   מכונות דפדפן שתומכות ב-Reporting-Endpoints ישתמשו ב-Reporting-Endpoints, ומכונות שלא תומכות ב-Reporting-Endpoints יחזרו ל-Report-To. הפורמט של הבקשה והדוח זהה בגרסה v0 ובגרסה v1.

2. שלב 2 (עכשיו): מוודאים שהכותרת Reporting-Endpoints מוגדרת בכל התשובות שעשויות ליצור דוחות.

   בגרסה 0, אפשר להגדיר נקודות קצה לדיווח בתגובות מסוימות בלבד, ומסמכים אחרים (דפים) במקור הזה ישתמשו בנקודת הקצה 'הסביבתית' הזו. בגרסה 1, בגלל ההבדל בהיקף, צריך להגדיר את הכותרת Reporting-Endpoints בכל התשובות שעשויות ליצור דוחות.

3. שלב 3 (מתחילים מאוחר יותר): אחרי שכל המשתמשים או רובם יעדכנו להתקנות מאוחרות יותר של Chrome או Edge (גרסה 96 ואילך), מסירים את Report-To (v0) ושומרים רק את Reporting-Endpoints.

   יש חריג אחד: אם אתם צריכים דוחות של רישום שגיאות ברשת, כדאי להשאיר את Report-To עד שיהיה מנגנון חדש לרישום שגיאות ברשת.

דוגמאות לקוד זמינות בספר המתכונים להעברה.

שלבי ההעברה של דיווח CSP

יש שתי דרכים להגדיר דוחות על הפרות של Content-Security-Policy:

• באמצעות כותרת ה-CSP בלבד, באמצעות ההוראה report-uri. יש תמיכה רחבה בדפדפנים, כולל Chrome, ‏ Firefox, ‏ Safari ו-Edge. הדוחות נשלחים עם סוג התוכן application/csp-report ובפורמט שספציפי ל-CSP. הדוחות האלה נקראים 'דוחות CSP ברמה 2' והם לא מסתמכים על Reporting API.
• ב-Reporting API, האפשרות הזו זמינה באמצעות הכותרת Report-To (קודמת) או הכותרת החדשה יותר Reporting-Endpoints (גרסה 1). התכונה הזו נתמכת רק ב-Chrome וב-Edge. לבקשות הדוחות יש את אותו פורמט כמו לבקשות אחרות של Reporting API, ואותו סוג תוכן application/reports+json.

לא מומלץ יותר להשתמש בגישה הראשונה (רק report-uri), ולגישה השנייה יש כמה יתרונות. באופן ספציפי, הוא מאפשר לכם להשתמש בדרך אחת כדי להגדיר דיווח לכל סוגי הדוחות, וגם להגדיר נקודת קצה גנרית (כי לכל בקשות הדוחות שנוצרות דרך Reporting API⏤CSP וגם אחרים⏤יש את אותו פורמט application/reports+json.

עם זאת, רק כמה דפדפנים תומכים ב-report-to. לכן מומלץ להמשיך להשתמש ב-report-uri לצד הגישה של Reporting API (Report-To או, עדיף, Reporting-Endpoints) כדי לקבל דוחות על הפרות של CSP מכמה דפדפנים. בדפדפן שמזהה את report-uri ואת report-to, המערכת תתעלם מ-report-uri אם report-to נמצא. בדפדפן שמזהה רק את report-uri, רק report-uri יילקח בחשבון.

1. שלב 1 (עכשיו): אם עדיין לא הוספתם אותו, מוסיפים את report-to לצד report-uri. בדפדפנים שתומכים רק ב-report-uri (Firefox) נעשה שימוש ב-report-uri, ובדפדפנים שתומכים גם ב-report-to(Chrome, ‏ Edge) נעשה שימוש ב-report-to. כדי לציין את נקודות הקצה בעלות השם שבהן תשתמשו ב-report-to, צריך להשתמש בשתי הכותרות Report-To ו-Reporting-Endpoints. כך תוכלו לקבל דוחות גם מלקוחות Chrome ו-Edge ישנים וגם מלקוחות חדשים.

2. שלב 3 (מתחילים מאוחר יותר): אחרי שכל המשתמשים או רובם יעדכנו להתקנות מאוחרות יותר של Chrome או Edge (גרסה 96 ואילך), מסירים את Report-To (v0) ושומרים רק את Reporting-Endpoints. משאירים את report-uri כדי להמשיך לקבל דוחות בדפדפנים שתומכים רק בו.

דוגמאות לקוד של השלבים האלה מפורטות במאמר העברת דיווח של שותף עצמאי לדיווח (CSP).

מיגרציה: קוד לדוגמה

סקירה כללית

אם אתם משתמשים ב-Reporting API הקודם (גרסה 0) כדי לקבל דוחות על הפרות של COOP (כותרת Cross-Origin-Opener-Policy), של COEP (Cross-Origin-Embedder-Policy) או של מדיניות מסמך (כותרת Document-Policy): אין צורך לשנות את כותרות המדיניות האלה בעצמן במהלך ההעברה ל-Reporting API גרסה 1. מה שכן צריך לעשות הוא לעבור מהכותרת הקודמת Report-To לכותרת החדשה Reporting-Endpoints.

אם אתם משתמשים ב-Reporting API הקודם (גרסה 0) כדי לקבל דוחות על הפרות של CSP (כותרת Content-Security-Policy), יכול להיות שתצטרכו לשנות את Content-Security-Policy כחלק מהמעבר ל-Reporting API החדש (גרסה 1).

העברה בסיסית

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

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

מעקב אחרי כל הדפים

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

העברת דיווח של ספקי שירות מנוהלים

Content-Security-Policy: ...; report-uri https://reports.example/main

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

קריאה נוספת

• מעקב אחרי אפליקציית האינטרנט באמצעות Reporting API (הפוסט הראשי בנושא Reporting API)
• מפרט: Reporting API מדור קודם (גרסה 0)
• מפרט: Reporting API החדש (גרסה 1)

תודה רבה ל-Ian Clelland, ל-Eiji Kitamura ול-Milica Mihajlija על הביקורות וההצעות שלהם לגבי המאמר הזה.