Skip to content

Commit 033cc83

Browse files
BenoitZugmeyerBenoitZugmeyer
authored
🤖 bring v7 upgrade skill to main (#4541)
1 parent c8c61f0 commit 033cc83

1 file changed

Lines changed: 163 additions & 0 deletions

File tree

  • .claude/skills/upgrade-browser-sdk-v7

‎.claude/skills/upgrade-browser-sdk-v7/SKILL.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
name: upgrade-browser-sdk-v7
3+
description: Use when upgrading Datadog Browser SDK from v6 to v7, when encountering removed options like betaEncodeCookieOptions, allowFallbackToLocalStorage, trackBfcacheViews, usePciIntake, or when a project references datadoghq-browser-agent.com CDN with /v6/ paths
4+
---
5+
6+
# Upgrade Datadog Browser SDK to v7
7+
8+
Systematic migration guide from v6 to v7. Follow steps 1-6 in order. Each step includes a search pattern to find affected code.
9+
10+
## Step 1: Update SDK version
11+
12+
**CDN setup** — update script `src` URLs:
13+
14+
| v6 pattern | v7 replacement |
15+
| -------------------------------------------------------- | -------------------------------------------------------- |
16+
| `datadoghq-browser-agent.com/us1/v6/datadog-rum.js` | `datadoghq-browser-agent.com/us1/v7/datadog-rum.js` |
17+
| `datadoghq-browser-agent.com/us1/v6/datadog-logs.js` | `datadoghq-browser-agent.com/us1/v7/datadog-logs.js` |
18+
| `datadoghq-browser-agent.com/us1/v6/datadog-rum-slim.js` | `datadoghq-browser-agent.com/us1/v7/datadog-rum-slim.js` |
19+
20+
Replace `us1` with your site: `eu1`, `us3`, `us5`, `ap1`, `ap2`. For US1-FED, the pattern is flat: `datadog-rum-v7.js` (no site prefix).
21+
22+
Search: `grep -r "datadoghq-browser-agent.com.*v6" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx"`
23+
24+
**npm setup** — update `package.json` dependencies:
25+
26+
```
27+
"@datadog/browser-rum": "^7.0.0"
28+
"@datadog/browser-logs": "^7.0.0"
29+
"@datadog/browser-rum-slim": "^7.0.0"
30+
```
31+
32+
Then run your package manager (`npm install`, `yarn install`, etc.) and rebuild.
33+
34+
Also upgrade framework integrations to v7: `@datadog/browser-rum-react`, `@datadog/browser-rum-angular`, `@datadog/browser-rum-vue`, `@datadog/browser-rum-nextjs`.
35+
36+
Search: `grep -r "@datadog/browser-" package.json`
37+
38+
## Step 2: Add `crossorigin="anonymous"` (CDN only)
39+
40+
v7 CDN bundles use ESM dynamic imports. **Every** `<script>` tag loading the SDK must have `crossorigin="anonymous"`:
41+
42+
```html
43+
<script src="https://www.datadoghq-browser-agent.com/us1/v7/datadog-rum.js" crossorigin="anonymous"></script>
44+
```
45+
46+
For **dynamically created** script elements:
47+
48+
```js
49+
const script = document.createElement('script')
50+
script.crossOrigin = 'anonymous' // Must set BEFORE setting src
51+
script.src = 'https://www.datadoghq-browser-agent.com/us1/v7/datadog-rum.js'
52+
```
53+
54+
Search: `grep -rn "datadoghq-browser-agent" --include="*.html" --include="*.js" --include="*.ts"`
55+
56+
Check every match for the `crossorigin` attribute (HTML) or `.crossOrigin` property (JS).
57+
58+
## Step 3: Remove deprecated options
59+
60+
Search init calls for these options and apply replacements:
61+
62+
### Removed from Core (affects both RUM and Logs)
63+
64+
| Option | Action |
65+
| ----------------------------- | -------------------------------------------------------------- |
66+
| `betaEncodeCookieOptions` | Delete. Cookie encoding is always enabled. |
67+
| `allowFallbackToLocalStorage` | Replace with `sessionPersistence: ['cookie', 'local-storage']` |
68+
69+
### Removed from RUM
70+
71+
| Option | Action |
72+
| ----------------------------- | ------------------------------------------------ |
73+
| `trackBfcacheViews` | Delete. BFCache views are always tracked. |
74+
| `trackEarlyRequests` | Delete. Early requests are always collected. |
75+
| `betaTrackActionsInShadowDom` | Delete. Shadow DOM action tracking is always on. |
76+
77+
### Removed from Logs
78+
79+
| Option | Action |
80+
| -------------- | ----------------------------------------------------------------------------------------------------- |
81+
| `usePciIntake` | Delete. Standard intake is now PCI compliant. Update CSP if you had PCI-specific domains allowlisted. |
82+
83+
Search: `grep -rn 'betaEncodeCookieOptions|allowFallbackToLocalStorage|trackBfcacheViews|trackEarlyRequests|betaTrackActionsInShadowDom|usePciIntake' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.html"`
84+
85+
## Step 4: Update changed APIs
86+
87+
### 4a. `forwardErrorsToLogs` + `forwardConsoleLogs` (Logs)
88+
89+
These are now **independent**. In v6, `forwardErrorsToLogs: true` silently forwarded `console.error()`. In v7, it only controls unhandled errors.
90+
91+
**If you use `forwardErrorsToLogs: true`**, add `"error"` to your `forwardConsoleLogs` array to preserve v6 behavior:
92+
93+
```js
94+
DD_LOGS.init({
95+
forwardErrorsToLogs: true,
96+
forwardConsoleLogs: ['error', 'warn'], // add 'error' explicitly
97+
})
98+
```
99+
100+
Search: `grep -rn "forwardErrorsToLogs" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.html"`
101+
102+
### 4b. `startDurationVital` / `stopDurationVital` (RUM)
103+
104+
The `DurationVitalReference` object is replaced by a `vitalKey` string:
105+
106+
```js
107+
// v6
108+
const ref = DD_RUM.startDurationVital('checkout')
109+
DD_RUM.stopDurationVital(ref)
110+
111+
// v7
112+
DD_RUM.startDurationVital('checkout', { vitalKey: 'checkout-key' })
113+
DD_RUM.stopDurationVital('checkout', { vitalKey: 'checkout-key' })
114+
```
115+
116+
Search: `grep -rn 'startDurationVital|stopDurationVital|DurationVitalReference' --include="*.js" --include="*.ts" --include="*.tsx"`
117+
118+
### 4c. Plugin API: `strategy` removed (RUM)
119+
120+
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.
121+
122+
Search: `grep -rn "strategy" --include="*.js" --include="*.ts" --include="*.tsx"` (look for plugin definitions)
123+
124+
## Step 5: Review behavioral changes (no code required, but may need attention)
125+
126+
These are **default changes** — no code breaks, but behavior differs from v6:
127+
128+
| Change | Impact | Action if needed |
129+
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
130+
| `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. |
131+
| `enablePrivacyForActionName` defaults to `true` | Click action names follow privacy level. May be masked. | Use the [Datadog build plugin](https://github.com/DataDog/build-plugins) or set `enablePrivacyForActionName: false`. |
132+
| `propagateTraceBaggage` defaults to `true` | CORS: cross-origin APIs must allow `baggage` header. | Add `"baggage"` to `Access-Control-Allow-Headers`, or set `propagateTraceBaggage: false`. |
133+
| Deterministic sampling | Sampling computed from session ID + rate, not stored. Consistent across pages. | Review if you use different sample rates on different pages. |
134+
| FID removed | First Input Delay no longer collected. | Use INP (Interaction to Next Paint) instead. |
135+
| `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`. |
136+
| Document resource `initiatorType` changed | `"initial_document"` becomes `"navigation"`. Duration may differ slightly. | Update any code inspecting document resource `performanceEntry`. |
137+
| Action names may change | Tree walker strategy always used (including Shadow DOM). | Review if you have monitors based on specific action names. |
138+
| Cancelled request errors removed (Logs) | Aborted fetch/XHR no longer generate network error logs. | No action needed — reduces noise. |
139+
| Logs always requires session storage | Without cookies or localStorage, Logs SDK won't start. | Use `sessionPersistence: 'memory'` for worker environments. |
140+
| Session Replay: Change Records | New serialization format. More accurate, less bandwidth. | Update if you depend on raw segment format. |
141+
| 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`). |
142+
143+
## Step 6: Update infrastructure
144+
145+
- **CSP**:
146+
- Add `crossorigin` to script-src.
147+
- Update chunk names like `datadog*-datadog-rum.js` (e.g. `datadogRecorder`, `datadogProfiler`).
148+
- If you removed `usePciIntake`, update CSP for standard intake domain.
149+
- **Cookies**: Add `_dd_s_v2` to cookie allowlists. The SDK auto-migrates from `_dd_s` on first load. Rollback to v6 starts new sessions.
150+
- **CORS** (if using `allowedTracingUrls`): Add `"baggage"` to `Access-Control-Allow-Headers` on traced origins — or set `propagateTraceBaggage: false`.
151+
- **Browser support**: Minimum Chrome 80+, Firefox 78+, Safari 14+ (ES2020). ~0.048% less coverage.
152+
153+
## Verification checklist
154+
155+
After upgrading, confirm:
156+
157+
- [ ] SDK loads without console errors
158+
- [ ] `crossorigin="anonymous"` on all CDN script tags
159+
- [ ] No references to removed options in init config
160+
- [ ] Session Replay recordings working (if used)
161+
- [ ] Distributed tracing working (no CORS errors from baggage header)
162+
- [ ] No `_dd_s` cookie remaining after first page load (should be `_dd_s_v2`)
163+
- [ ] Action names acceptable under new privacy defaults

0 commit comments

Comments
 (0)