יש גרסה חדשה של Reporting API. הוא פרטי יותר ויש סיכוי גבוה יותר שתהיה תמיכה בו בדפדפנים שונים.
ה-Reporting API מאפשר לכם לקבל הודעות על שגיאות שמתרחשות באתר בזמן שהמבקרים משתמשים בו. הוא נותן את החשיפה של התערבות בדפדפן, קריסות של דפדפנים, הפרות מדיניות אבטחת תוכן, הפרות של COOP/COEP, אזהרות לגבי הוצאה משימוש ועוד.
יש גרסה חדשה של Reporting API. ה-API החדש דק יותר, ויש סבירות גבוהה יותר שהוא נתמך בכל הדפדפנים.
סיכום
מפתחי אתרים
אם כבר יש לכם פונקציונליות דיווח באתר: עוברים לגרסה 1 באמצעות הכותרת החדשה.
(Reporting-Endpoints
), אבל להשאיר את הכותרת מהדור הקודם למשך זמן מה (Report-To
).
מידע נוסף זמין בקטע העברה: קוד לדוגמה.
אם אתם מוסיפים כרגע פונקציונליות דיווח לאתר: השתמשו רק בכותרת החדשה
(Reporting-Endpoints
).
⚠️ בשני המקרים, חשוב להגדיר את הכותרת Reporting-Endpoints
בכל התשובות שעשויות להיות
להפיק דוחות.
מפתחים של שירותי דיווח
אם אתם מתחזקים שירות של נקודת קצה או מפעילים שירות משלכם, כדאי לצפות לנפח תנועה גדול יותר במהלך השימוש
או מפתחים חיצוניים עוברים ל-Reporting API v1 (הכותרת Reporting-Endpoints
).
בהמשך מופיעים פרטים וקוד לדוגמה.
רישום של שגיאות רשת
נפתח מנגנון חדש לרישום שגיאות רשת. ברגע שזה יהיה זמין, צריך לעבור מ-Reporting API גרסה 0 למנגנון החדש.
הדגמה וקוד
- אתר הדגמה: new Reporting API (גרסה 1)
- קוד לאתר ההדגמה
ההבדלים בין גרסה v0 לבין גרסה 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
- היקף הדוח שונה.
אם משתמשים בגרסה 0, אפשר להגדיר נקודות קצה לדיווח רק על תשובות מסוימות. מסמכים (דפים) אחרים המקור ישתמש אוטומטית בנקודות הקצה ברקע.
בגרסה 1, צריך להגדיר את הכותרת Reporting-Endpoints
בכל התשובות שעשויות ליצור
דוחות.
- שני ממשקי ה-API תומכים באותם סוגי דוחות, למעט חריג אחד: גרסה 1 לא תומכת בדוחות שגיאות רשת. מידע נוסף זמין בשלבי ההעברה.
- אין תמיכה ב-v0 בכל הדפדפנים, ולא תהיה אפשרות לתמוך בה. יש סבירות גבוהה יותר שתהיה תמיכה בגרסה 1 בדפדפנים מרובים בעתיד.
מה לא משתנה
- הפורמט והמבנה של הדוחות לא השתנו.
- הבקשה שנשלחה על ידי הדפדפן לנקודת הקצה נשארת בקשת
POST
שלContent-type
application/reports+json
. - מיפוי של נקודות קצה (endpoints) מסוימות לסוגי דוחות מסוימים נתמך גם בגרסה v0 וגם בגרסה 1.
- התפקיד של נקודת הקצה
default
לא משתנה. לגרסה 1 של Reporting API אין השפעה על
ReportingObserver
. האפליקציהReportingObserver
ממשיכה לקבל גישה לכל הדוחות הגלויים, והפורמט שלהם הוא זהה.
כל ההבדלים בין גרסה v0 לבין גרסה 1
Legacy Reporting API (גרסה 0) כותרת Report-To |
Reporting API החדש (גרסה 1) כותרת Reporting-Endpoints |
|
---|---|---|
תמיכה בדפדפנים | Chrome מגרסה 69 ואילך ו-Edge 69 ואילך. | Chrome מגרסה 96 ואילך ו-Edge מגרסה 96 ואילך. Firefox תומך. אין ל-Safari התנגדות. מעיינים בקטע אותות מהדפדפן. |
נקודות קצה (endpoints) | שולחת דוחות לכל מספר אוספים של דוחות (מוגדרות כמה כתובות URL לכל קבוצה של נקודות קצה). | שולחת דוחות לאוסף דוחות ספציפיים (רק כתובת URL אחת מוגדרת לכל נקודת קצה). |
פלטפורמת API | נעשה שימוש בכותרת `Report-To` כדי להגדיר קבוצות של נקודות קצה (endpoint) בעלות שם. |
משתמשת בכותרת `Reporting-Endpoints` כדי להגדיר נקודות קצה (endpoints) בעלות שם. |
סוגי הדוחות שניתן להפיק באמצעות ה-API הזה |
|
ללא שינוי, למעט מ-Network Error Logging (NEL): הדבר לא נתמך ב-Reporting API החדש (v1). |
היקף הדוח | מקור. הכותרת Report-To של מסמך משפיעה על מסמכים (דפים) אחרים מאותו מקור.
השדה url בדוח עדיין משתנה בהתאם למסמך.
|
מסמך. הכותרת Reporting-Endpoints של מסמך משפיעה רק על המסמך הזה.
השדה url בדוח עדיין משתנה בהתאם למסמך.
|
בידוד דוחות (קיבוץ) | מסמכים (דפים) או אתרים/מקורות שונים שמייצרים דוח בערך באותה שעה, ושיש להם אותה נקודת קצה לדיווח, יקובצו יחד: הם יישלחו באותה הודעה לנקודת הקצה לדיווח. |
|
תמיכה באיזון עומסים / עדיפויות | כן | לא |
מפתחי נקודות קצה (endpoint): צפויה עלייה של תנועת הגולשים
אם הגדרתם שרת משלכם כנקודת קצה לדיווח, או אם אתם מפתחים או מתחזקים אוסף דוחות כשירות, אפשר לצפות לתנועה רבה יותר לנקודת הקצה הזו.
הסיבה לכך היא שלא מקובצים דוחות ב-Reporting API v1 כמו שהם ב-Reporting API v0. לכן, כשמפתחי אפליקציות יתחילו לעבור ל-Reporting API v1, מספר הדוחות יישארו דומות, אבל נפח הבקשות לשרת נקודת הקצה יגדל.
מפתחי אפליקציות: Migrate to Reporting-Endpoints
(v1)
מה עליך לעשות?
יש כמה יתרונות לשימוש בגרסה החדשה של Reporting API (גרסה 1) ✅:
- האותות של הדפדפן הם חיוביים. כלומר, צפויה תמיכה בדפדפנים שונים בגרסה 1 (בניגוד ל-v0 שנתמכת רק ב-Chrome קצה).
- ה-API פחות נקי.
- אנחנו מפתחים את הכלים בהתאם לגרסה החדשה של Reporting API (גרסה 1).
כדאי להביא בחשבון את הדברים הבאים:
- אם באתר שלך כבר נעשה שימוש ב-Reporting API v0 עם הכותרת
Report-To
, יש לעבור אל Reporting API גרסה 1 (מידע נוסף זמין בשלבים להעברה). אם האתר כבר משתמש פונקציונליות של דיווח על הפרות של מדיניות Content-Security-Policy. השלבים הספציפיים להעברה לדיווח על CSP זמינים במאמר. - אם באתר שלכם עדיין לא נעשה שימוש ב-Reporting API ועכשיו אתם מוסיפים פונקציונליות של דיווח:
להשתמש ב-Reporting API החדש (v1) (הכותרת
Reporting-Endpoints
). יש חריג אחד this: אם אתם צריכים להשתמש ב-Network Error Logging, השתמשוReport-To
(v0). רישום של שגיאות רשת לא נתמכת כרגע ב-Reporting API v1. מנגנון חדש לרישום שגיאות רשת עד שיהיה זמין, צריך להשתמש ב-Reporting API v0. אם אתם צריכים רישום של שגיאות רשת לצד סוגי הדוחות האחרים, צריך להשתמש גם ב-Report-To
(v0) וגם ב-Reporting-Endpoints
(v1). v0 נותן לך Network Error Logging ו-v1 נותנת דוחות מכל הסוגים האחרים.
שלבי ההעברה
היעד שלכם בהעברה הזו הוא לא לאבד את הדוחות שהשתמשתם בהם בגרסה 0.
שלב 1 (עשה עכשיו): השתמש בשתי הכותרות:
Report-To
(v0) ו-Reporting-Endpoints
(v1).כך תקבלו:
- דוחות מלקוחות חדשים יותר של Chrome ו-Edge, הודות ל-
Reporting-Endpoints
(גרסה 1). - דוחות מלקוחות ישנים יותר של Chrome ו-Edge הודות ל-
Report-To
(גרסה 0).
מופעי דפדפן שתומכים ב-
Reporting-Endpoints
ישתמשו ב-Reporting-Endpoints
, וגם מופעים שלא יחזרו ל-Report-To
. פורמט הבקשה זהה לפורמט הדוח עבור v0 ו-v1.- דוחות מלקוחות חדשים יותר של Chrome ו-Edge, הודות ל-
שלב 2 (לעשות עכשיו): מוודאים שהכותרת
Reporting-Endpoints
מוגדרת לכל התשובות יכול ליצור דוחות.בגרסה 0 אפשר להגדיר נקודות קצה לדיווח רק בחלק מהתשובות ובמסמכים אחרים (דפים) במקור הזה ישתמשו בערך "סביבתי" נקודת הקצה. עם גרסה 1, בגלל ההבדל את ההיקף, צריך להגדיר את הכותרת
Reporting-Endpoints
בכל התשובות שעשויות ליצור דוחות.שלב 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. הדוחות האלה נקראים 'דוחות ברמה 2 של CSP' ולעשות לא מסתמכות על Reporting API. - באמצעות Reporting API, דרך הכותרת
Report-To
(מדור קודם) או גרסה חדשה יותרReporting-Endpoints
(גרסה 1). האפשרות הזו נתמכת רק ב-Chrome וב-Edge. בקשות לדיווח כוללות את אותו פורמט כמו בקשות אחרות של Reporting API, ואותו סוג תוכןapplication/reports+json
.
שימוש בגישה הראשונה (רק report-uri
) לא מומלץ יותר ולשימוש בגישה השנייה יש כמה יתרונות. באופן ספציפי, התכונה הזו מאפשרת להשתמש באותה דרך שבה אפשר להגדיר דיווח לכל סוגי הדוחות, וגם להגדיר נקודת קצה (endpoint) גנרית (כי כל הבקשות לדוחות שנוצרות דרך 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 (עשה זאת עכשיו): אם עדיין לא הוספת אותו, צריך להוסיף את
report-to
לצדreport-uri
. דפדפנים שתומכים רק ב-report-uri
(Firefox) ישתמשו ב-report-uri
, ודפדפנים שגם התמיכה ב-report-to
(Chrome, Edge) תשתמש ב-report-to
. כדי לציין את נקודות הקצה בעלות השם, צריך להשתמש ב-report-to
, יש להשתמש גם בכותרותReport-To
וגם בכותרותReporting-Endpoints
. כך אפשר לקבל דוחות מלקוחות ישנים וחדשים יותר של Chrome ו-Edge.שלב 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
): אין צורך לשנות את כותרות המדיניות האלה עצמן במהלך ההעברה
לדיווח על גרסה 1 של Reporting API. מה שצריך לעשות הוא לעבור מהכותרת הקודמת של 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(...) });
העברה של דיווח CSP
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)
- מפרט: גרסה 1 של Reporting API
תמונה ראשית (Hero) של Nine Koepfer / @enka80 מופעלת ביטול הפתיחה, נערכה. ברוב תודה לאיאן Clelland, Eiji Kitamura ו-Milica Mihajlija (הביקורות וההצעות שלהם בנושא הזה) מאמר.