Signatur
Beschreibung
toJSON() ist die Serialisierungsmethode der Schnittstelle PerformanceSoftNavigation. Sie gibt ein einfaches Objekt zurück, das alle serialisierbaren Eigenschaften des Eintrags enthält. Dazu gehören die von PerformanceEntry geerbten Felder (name, entryType, startTime, duration) und die Felder für weiche Navigationen, zum Beispiel navigationId.
Eine weiche Navigation (engl. soft navigation) ist ein Seitenwechsel innerhalb einer Single-Page-Application. Er wird durch eine Nutzerinteraktion ausgelöst und ändert die URL über die History-API, ohne ein neues Dokument zu laden. Der Browser erzeugt dafür Einträge vom Typ "soft-navigation", die man mit einem PerformanceObserver beobachten kann.
Die Methode braucht man vor allem, um solche Einträge an einen Analyse-Endpunkt zu schicken (Real User Monitoring), zum Beispiel mit navigator.sendBeacon() oder fetch(). Man ruft sie selten direkt auf, denn JSON.stringify() nutzt toJSON() automatisch. Ohne diese Methode würde JSON.stringify() nur {} liefern, weil die Eigenschaften als Getter am Prototyp liegen und nicht als eigene Eigenschaften des Objekts.
Rückgabewert
PerformanceSoftNavigation-Eintrags, z. B. name, entryType, startTime, duration und navigationId.Beispiele
Weiche Navigationen beobachten und als JSON ausgeben
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
// toJSON() liefert ein einfaches Objekt
console.log(entry.toJSON());
}
});
observer.observe({ type: 'soft-navigation', buffered: true });JSON.stringify() ruft toJSON() automatisch auf
const [entry] = performance.getEntriesByType('soft-navigation');
if (entry) {
// Beide Varianten ergeben denselben String
console.log(JSON.stringify(entry));
console.log(JSON.stringify(entry.toJSON()));
} else {
console.log('Noch keine weiche Navigation erfasst.');
}Einträge per Beacon an einen RUM-Endpunkt senden
const puffer = [];
const observer = new PerformanceObserver((list) => {
puffer.push(...list.getEntries().map((e) => e.toJSON()));
});
// Vorher prüfen, ob der Browser den Eintragstyp kennt
if (PerformanceObserver.supportedEntryTypes?.includes('soft-navigation')) {
observer.observe({ type: 'soft-navigation', buffered: true });
}
document.addEventListener('visibilitychange', () => {
if (document.visibilityState === 'hidden' && puffer.length > 0) {
navigator.sendBeacon('/rum/soft-navigations', JSON.stringify(puffer));
puffer.length = 0;
}
});// Wichtig · Fallstricke
Experimentell: PerformanceSoftNavigation gibt es bisher nur in Chromium-Browsern, und zwar über ein Origin Trial oder das Flag Experimental Web Platform features. Firefox und Safari unterstützen es derzeit nicht. Prüfen Sie die Unterstützung vorab mit PerformanceObserver.supportedEntryTypes.includes('soft-navigation').
Felder können sich ändern: Die Spezifikation wird noch weiterentwickelt. Welche Felder das Objekt enthält, hängt deshalb von der Browserversion ab. Werten Sie serverseitig robust aus und behandeln Sie fehlende Felder.
Datenschutz: name enthält die vollständige URL, also auch Query-Parameter. Diese können personenbezogene Daten oder Tokens enthalten. Entfernen oder kürzen Sie solche Teile, bevor Sie Einträge an Analyse-Dienste senden.
Zeitwerte: startTime ist relativ zu performance.timeOrigin der ursprünglichen harten Navigation. Es ist also kein absoluter Zeitstempel.