Skills DirectorySearch all skills ↗AI agent skill · by @datadog-labs
Upgrade Browser Sdk V7
Upgrade Datadog Browser SDK from v6 to v7. Use when encountering removed options like betaEncodeCookieOptions, allowFallbackToLocalStorage, trackBfcacheViews, usePciIntake, changed APIs like forwardErrorsToLogs, startDurationVital, stopDurationVital, or when a project references datadoghq-browser-agent.com CDN with /v6/ paths.
Archived 2026-10-23 · Source updated 2026-09-17 · License: MIT. Check the original repository for the latest version.
SKILL.md instructions
# Upgrade Datadog Browser SDK to v7
Systematic migration guide from v6 to v7. Follow steps 1-6 in order. Each step includes a search pattern to find affected code.
## Step 1: Update SDK version
**CDN setup** — update script `src` URLs:
| v6 pattern | v7 replacement |
| -------------------------------------------------------- | -------------------------------------------------------- |
| `datadoghq-browser-agent.com/us1/v6/datadog-rum.js` | `datadoghq-browser-agent.com/us1/v7/datadog-rum.js` |
| `datadoghq-browser-agent.com/us1/v6/datadog-logs.js` | `datadoghq-browser-agent.com/us1/v7/datadog-logs.js` |
| `datadoghq-browser-agent.com/us1/v6/datadog-rum-slim.js` | `datadoghq-browser-agent.com/us1/v7/datadog-rum-slim.js` |
Replace `us1` with your site: `eu1`, `us3`, `us5`, `ap1`, `ap2`. For US1-FED, the pattern is flat with no site prefix: `datadog-rum-v7.js`, `datadog-logs-v7.js`, `datadog-rum-slim-v7.js`.
Search: `grep -r "datadoghq-browser-agent.com.*v6" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"`
**npm setup** — update `package.json` dependencies:
```
"@datadog/browser-rum": "^7.0.0"
"@datadog/browser-logs": "^7.0.0"
"@datadog/browser-rum-slim": "^7.0.0"
```
Then run your package manager (`npm install`, `yarn install`, etc.) and rebuild.
Also upgrade framework integrations to v7: `@datadog/browser-rum-react`, `@datadog/browser-rum-angular`, `@datadog/browser-rum-vue`, `@datadog/browser-rum-nextjs`.
Search: `grep -r "@datadog/browser-" --include="package.json" .`
## Step 2: Add `crossorigin="anonymous"` (CDN only)
v7 CDN bundles use ESM dynamic imports. **Every** `<script>` tag loading the SDK must have `crossorigin="anonymous"`:
```html
<script src="https://www.datadoghq-browser-agent.com/us1/v7/datadog-rum.js" crossorigin="anonymous"></script>
```
For **dynamically created** script elements:
```js
const script = document.createElement('script')
script.crossOrigin = 'anonymous' // Must set BEFORE setting src
script.src = 'https://www.datadoghq-browser-agent.com/us1/v7/datadog-rum.js'
```
Search: `grep -rn "datadoghq-browser-agent" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"`
Check every match for the `crossorigin` attribute (HTML) or `.crossOrigin` property (JS).
## Step 3: Remove deprecated options
Search init calls for these options and apply replacements:
### Removed from Core (affects both RUM and Logs)
| Option | Action |
| ----------------------------- | -------------------------------------------------------------- |
| `betaEncodeCookieOptions` | Delete. Cookie encoding is always enabled. |
| `allowFallbackToLocalStorage` | Replace with `sessionPersistence: ['cookie', 'local-storage']` |
### Removed from RUM
| Option | Action |
| ----------------------------- | ------------------------------------------------ |
| `trackBfcacheViews` | Delete. BFCache views are always tracked. |
| `trackEarlyRequests` | Delete. Early requests are always collected. |
| `betaTrackActionsInShadowDom` | Delete. Shadow DOM action tracking is always on. |
### Removed from Logs
| Option | Action |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| `usePciIntake` | Delete. Standard intake is now PCI compliant. Update CSP if you had PCI-specific domains allowlisted. |
Search: `grep -rn 'betaEncodeCookieOptions\|allowFallbackToLocalStorage\|trackBfcacheViews\|trackEarlyRequests\|betaTrackActionsInShadowDom\|usePciIntake' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"`
## Step 4: Update changed APIs
### 4a. `forwardErrorsToLogs` + `forwardConsoleLogs` (Logs)
These are now **independent**. In v6, `forwardErrorsToLogs: true` had a side effect: it also forwarded `console.error()` calls to Logs. In v7, that side effect is removed.
- `forwardErrorsToLogs` — controls forwarding of **unhandled errors** (uncaught exceptions, unhandled rejections) and **network errors** to Logs. **Keep this unchanged.**
- `forwardConsoleLogs` — controls forwarding of **`console.error()` calls** to Logs. Add `'error'` here to restore the v6 side effect.
**Only add `forwardConsoleLogs: ['error']` when `forwardErrorsToLogs` is `true` or omitted** — in v6 the side effect only applied when the option was enabled (explicitly or via the default). If `forwardErrorsToLogs: false`, there was no side effect to restore; leave it unchanged.
```js
// v6 — forwardErrorsToLogs: true (explicit or omitted, which defaults to true)
DD_LOGS.init({
forwardErrorsToLogs: true,
forwardConsoleLogs: ['warn'], // example: existing levels
})
// v7 — add 'error' to restore the side effect; preserve any existing levels
DD_LOGS.init({
forwardErrorsToLogs: true, // unchanged
forwardConsoleLogs: ['warn', 'error'], // add 'error'
})
// v6 — forwardErrorsToLogs: false → no side effect existed; nothing to add
DD_LOGS.init({
forwardErrorsToLogs: false, // leave unchanged, do NOT add forwardConsoleLogs: ['error']
})
```
Do **not** replace `forwardErrorsToLogs` with `forwardConsoleLogs` — they control different things.
Search for explicit config: `grep -rn "forwardErrorsToLogs" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"`
Also search for Logs init calls that may be relying on the default (`forwardErrorsToLogs` defaults to `true` in v6, so omitting it still had the side effect): `grep -rn "DD_LOGS\.init\|datadogLogs\.init" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"`
For any Logs init call where `forwardErrorsToLogs` is `true` or omitted, and `forwardConsoleLogs` does not already include `'error'` or `'all'`, add `'error'` to preserve v6 behavior.
### 4b. `startDurationVital` / `stopDurationVital` (RUM)
The `DurationVitalReference` object is replaced by a `vitalKey` string. **`startDurationVital` now returns `void`** — the v7 API is fire-and-forget; the vital name string is all you need.
```js
// v5/v6 — ref-based (CDN: DD_RUM, npm: datadogRum)
var ref = DD_RUM.startDurationVital('checkout_flow')
// ... async work ...
DD_RUM.stopDurationVital(ref)
// v7
DD_RUM.startDurationVital('checkout_flow', { vitalKey: 'checkout_flow' })
DD_RUM.stopDurationVital('checkout_flow', { vitalKey: 'checkout_flow' })
```
**This silently breaks in CDN/plain JS projects.** TypeScript catches it with a type error; plain JS does not. `ref` becomes `undefined` and `stopDurationVital(undefined)` is a no-op — the vital starts but never stops, so the event is never emitted.
**Step 1 — find all `startDurationVital`/`stopDurationVital` usages** (both CDN and npm patterns, all file types):
```
grep -rn 'startDurationVital\|stopDurationVital\|DurationVitalReference' \
--include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" \
--include="*.html" --include="*.svelte" --include="*.vue"
```
**Step 2 — find every variable that captures the return value** (this is the failure point):
```
grep -rEn '(var|const|let)\s+\w+\s*=\s*.+startDurationVital|[\w.]+\s*=\s*(window\.)?DD_RUM\.startDurationVital|[\w.]+\s*=\s*datadogRum\.startDurationVital' \
--include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" \
--include="*.svelte" --include="*.vue"
```
For every match: remove the variable assignment and update all uses of that variable in the corresponding `stopDurationVital` call to pass the vital name string directly.
**Step 3 — if the SDK is wrapped in a utility** (e.g. `startTiming` / `stopTiming`):
1. Update the wrapper — pass `vitalKey` to `startDurationVital`, return nothing.
2. Find callers that capture the wrapper return value:
```
grep -rEn '(var|const|let)\s+\w+\s*=\s*.+[Ss]tart[Tt]iming|(var|const|let)\s+\w+\s*=\s*.+[Ss]tart.+[Vv]ital' \
--include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" \
--include="*.html" --include="*.svelte" --include="*.vue"
```
3. Remove the capture and update the stop call to pass the vital name string directly:
```js
// Caller — before
var ref = startTiming('checkout_flow')
stopTiming(ref) // undefined in v7 → vital never stops
// Caller — after
startTiming('checkout_flow')
stopTiming('checkout_flow')
```
### 4c. Plugin API: `strategy` removed (RUM)
The `strategy` field has been removed from the plugin API. If you use `@datadog/browser-rum-react` or other plugin integrations, upgrade them to v7.
Search: `grep -rn "strategy" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"` (look for plugin definitions)
## Step 5: Review behavioral changes (no code required, but may need attention)
These are **default changes** — no code breaks, but behavior differs from v6:
| Change | Impact | Action if needed |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultPrivacyLevel` defaults to `"mask-user-input"` (was `"mask"`) | Less restrictive masking out of the box. Only user input is masked. | Set `defaultPrivacyLevel: "mask"` to preserve full masking. |
| `enablePrivacyForActionName` defaults to `true` | Action names are derived from `textContent` (not `innerText`) — CSS `text-transform` is no longer applied. A button with `style="text-transform: capitalize"` and raw text `"audio"` yields `"Audio"` in v6 but `"audio"` in v7. Names may also be masked based on privacy level. **Note:** setting this to `false` does not restore CSS-aware extraction — v7 always uses `textContent`. | Add `data-dd-action-name` attributes to elements whose display names relied on CSS transforms, or update monitors to match raw text values. Use the [Datadog build plugin](https://github.com/DataDog/build-plugins) for annotation-based control. |
| `propagateTraceBaggage` defaults to `true` | CORS: cross-origin APIs must allow `baggage` header. | Add `"baggage"` to `Access-Control-Allow-Headers`, or set `propagateTraceBaggage: false`. |
| Deterministic sampling | Sampling computed from session ID + rate, not stored. Consistent across pages. | Review if you use different sample rates on different pages. |
| FID removed | First Input Delay no longer collected. | Use INP (Interaction to Next Paint) instead. |
| `session_renewal` view loading type | Session-renewed views have `@view.loading_type:session_renewal` instead of `route_change`. | Update dashboards/monitors filtering on `@view.loading_type`. |
| Document resource `initiatorType` changed | `"initial_document"` becomes `"navigation"`. Duration may differ slightly. | Update any code inspecting document resource `performanceEntry`. |
| Action names may change | Tree walker + `textContent` always used in v7 (including Shadow DOM) — CSS `text-transform` is never reflected regardless of `enablePrivacyForActionName`. Monitors with case-sensitive filters on visually-transformed names may break. | Add `data-dd-action-name` attributes to affected elements, or update monitors to match raw text values. |
| Cancelled request errors removed (Logs) | Aborted fetch/XHR no longer generate network error logs. | No action needed — reduces noise. |
| Logs always requires session storage | Without cookies or localStorage, Logs SDK won't start. | Use `sessionPersistence: 'memory'` for worker environments. |
| Session Replay: Change Records | New serialization format. More accurate, less bandwidth. | Update if you depend on raw segment format. |
| Async chunk names prefixed with `datadog` | e.g., `datadogRecorder-<hash>-datadog-rum.js`, `datadogProfiler-<hash>-datadog-rum.js`. | Update CSP `script-src` rules or caching configs (allow `datadog*-datadog-rum.js`). |
## Step 6: Update infrastructure
- **CSP**:
- Add `crossorigin` to script-src.
- Update chunk names like `datadog*-datadog-rum.js` (e.g. `datadogRecorder`, `datadogProfiler`).
- If you removed `usePciIntake`, update CSP for standard intake domain.
- **Cookies**: Add `_dd_s_v2` to cookie allowlists. The SDK auto-migrates from `_dd_s` on first load. Rollback to v6 starts new sessions.
- **CORS**: Search for tracing config: `grep -rn "allowedTracingUrls\|propagateTraceBaggage" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"`. For any project with `allowedTracingUrls` and no explicit `propagateTraceBaggage: false`, add `"baggage"` to your existing `Access-Control-Allow-Headers` on traced origins — or set `propagateTraceBaggage: false` to opt out.
- **Browser support**: Minimum Chrome 80+, Firefox 78+, Safari 14+ (ES2020). ~0.048% less coverage.
## Common Mistakes
| Mistake | What goes wrong | Fix |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Replacing `forwardErrorsToLogs: true` with `forwardConsoleLogs: ['error']` | Unhandled errors (uncaught exceptions, unhandled rejections) stop being forwarded to Logs | Keep `forwardErrorsToLogs: true` unchanged and add `forwardConsoleLogs: ['error']` alongside it — they control different things |
| Updating `startDurationVital` wrapper but not its callers | Callers pass the old ref variable (now `undefined`) to `stopDurationVital` — vital never stops, event never emitted | After updating the wrapper, search for every caller that captures the return value and update the stop call to pass the vital name string directly |
| Missing `vitalKey` option on `stopDurationVital` | v7 `stopDurationVital` requires `{ vitalKey: string }` to identify which vital to stop | Pass the same string used in `startDurationVital`: `stopDurationVital('name', { vitalKey: 'name' })` |
| Not checking CDN/plain JS files for ref-based vitals | TypeScript projects surface this as a type error; plain JS silently breaks | Run the Step 2 grep explicitly — don't rely on type errors to find all sites |
## Verification checklist
After upgrading, confirm:
- [ ] SDK loads without console errors
- [ ] `crossorigin="anonymous"` on all CDN script tags
- [ ] No references to removed options in init config
- [ ] Session Replay recordings working (if used)
- [ ] Distributed tracing working (no CORS errors from baggage header)
- [ ] No `_dd_s` cookie remaining after first page load (should be `_dd_s_v2`)
- [ ] Action names acceptable under new privacy defaults
- [ ] No variables capturing the return value of `startDurationVital` (or wrappers around it) — all stop calls use the vital name string directly