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

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

Maud Nalpas

ה-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

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

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

מה לא משתנה

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

• לגרסה 1 של Reporting API אין השפעה על ReportingObserver. האפליקציה ReportingObserver ממשיכה לקבל גישה לכל הדוחות הגלויים, והפורמט שלהם הוא זהה.

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

מפתחי נקודות קצה (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. שלב 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.

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