upgrade-browser-sdk-v7

Par datadog-labs · agent-skills

Mettre à niveau le Datadog Browser SDK de la v6 vers la v7. À utiliser lorsque vous rencontrez des options supprimées comme `betaEncodeCookieOptions`, `allowFallbackToLocalStorage`, `trackBfcacheViews`, `usePciIntake`, ou lorsqu'un projet référence le CDN datadoghq-browser-agent.com avec des chemins `/v6/`.

npx skills add https://github.com/datadog-labs/agent-skills --skill upgrade-browser-sdk-v7

Mettre à niveau le SDK Datadog Browser vers v7

Guide de migration systématique de v6 à v7. Suivez les étapes 1-6 dans l'ordre. Chaque étape inclut un motif de recherche pour trouver le code affecté.

Étape 1 : Mettre à jour la version du SDK

Configuration CDN — mettez à jour les URLs src du script :

Motif v6 Remplacement v7
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

Remplacez us1 par votre site : eu1, us3, us5, ap1, ap2. Pour US1-FED, le motif est plat : datadog-rum-v7.js (aucun préfixe de site).

Recherche : grep -r "datadoghq-browser-agent.com.*v6" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx"

Configuration npm — mettez à jour les dépendances package.json :

"@datadog/browser-rum": "^7.0.0"
"@datadog/browser-logs": "^7.0.0"
"@datadog/browser-rum-slim": "^7.0.0"

Ensuite, exécutez votre gestionnaire de paquets (npm install, yarn install, etc.) et reconstruisez.

Mettez également à jour les intégrations de framework vers v7 : @datadog/browser-rum-react, @datadog/browser-rum-angular, @datadog/browser-rum-vue, @datadog/browser-rum-nextjs.

Recherche : grep -r "@datadog/browser-" package.json

Étape 2 : Ajouter crossorigin="anonymous" (CDN uniquement)

Les bundles CDN v7 utilisent des imports dynamiques ESM. Chaque balise <script> chargeant le SDK doit avoir crossorigin="anonymous" :

<script src="https://www.datadoghq-browser-agent.com/us1/v7/datadog-rum.js" crossorigin="anonymous"></script>

Pour les éléments script créés dynamiquement :

const script = document.createElement('script')
script.crossOrigin = 'anonymous' // Doit être défini AVANT de définir src
script.src = 'https://www.datadoghq-browser-agent.com/us1/v7/datadog-rum.js'

Recherche : grep -rn "datadoghq-browser-agent" --include="*.html" --include="*.js" --include="*.ts"

Vérifiez chaque résultat pour l'attribut crossorigin (HTML) ou la propriété .crossOrigin (JS).

Étape 3 : Supprimer les options dépréciées

Recherchez les appels d'init pour ces options et appliquez les remplacements :

Supprimées du noyau (affecte RUM et Logs)

Option Action
betaEncodeCookieOptions Supprimer. L'encodage des cookies est toujours activé.
allowFallbackToLocalStorage Remplacer par sessionPersistence: ['cookie', 'local-storage']

Supprimées de RUM

Option Action
trackBfcacheViews Supprimer. Les vues BFCache sont toujours suivies.
trackEarlyRequests Supprimer. Les requêtes précoces sont toujours collectées.
betaTrackActionsInShadowDom Supprimer. Le suivi des actions Shadow DOM est toujours activé.

Supprimées de Logs

Option Action
usePciIntake Supprimer. L'intake standard est maintenant conforme à la PCI. Mettez à jour la CSP si vous aviez des domaines spécifiques à la PCI en liste blanche.

Recherche : grep -rn 'betaEncodeCookieOptions|allowFallbackToLocalStorage|trackBfcacheViews|trackEarlyRequests|betaTrackActionsInShadowDom|usePciIntake' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.html"

Étape 4 : Mettre à jour les API modifiées

4a. forwardErrorsToLogs + forwardConsoleLogs (Logs)

Celles-ci sont maintenant indépendantes. En v6, forwardErrorsToLogs: true transmettait silencieusement console.error(). En v7, cela contrôle uniquement les erreurs non gérées.

Si vous utilisez forwardErrorsToLogs: true, ajoutez "error" à votre tableau forwardConsoleLogs pour préserver le comportement v6 :

DD_LOGS.init({
  forwardErrorsToLogs: true,
  forwardConsoleLogs: ['error', 'warn'], // ajoutez explicitement 'error'
})

Recherche : grep -rn "forwardErrorsToLogs" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.html"

4b. startDurationVital / stopDurationVital (RUM)

L'objet DurationVitalReference est remplacé par une chaîne vitalKey :

// v6
const ref = DD_RUM.startDurationVital('checkout')
DD_RUM.stopDurationVital(ref)

// v7
DD_RUM.startDurationVital('checkout', { vitalKey: 'checkout-key' })
DD_RUM.stopDurationVital('checkout', { vitalKey: 'checkout-key' })

Recherche : grep -rn 'startDurationVital|stopDurationVital|DurationVitalReference' --include="*.js" --include="*.ts" --include="*.tsx"

4c. Plugin API : strategy supprimée (RUM)

Le champ strategy a été supprimé de l'API plugin. Si vous utilisez @datadog/browser-rum-react ou d'autres intégrations de plugin, mettez-les à jour vers v7.

Recherche : grep -rn "strategy" --include="*.js" --include="*.ts" --include="*.tsx" (recherchez les définitions de plugin)

Étape 5 : Examiner les changements comportementaux (aucun code requis, mais peut nécessiter une attention)

Ce sont des changements de défaut — aucune rupture de code, mais le comportement diffère de v6 :

Changement Impact Action si nécessaire
defaultPrivacyLevel par défaut à "mask-user-input" (était "mask") Masquage moins restrictif par défaut. Seule l'entrée utilisateur est masquée. Définissez defaultPrivacyLevel: "mask" pour préserver le masquage complet.
enablePrivacyForActionName par défaut à true Les noms d'action clic suivent le niveau de confidentialité. Peuvent être masqués. Utilisez le plugin build Datadog ou définissez enablePrivacyForActionName: false.
propagateTraceBaggage par défaut à true CORS : les API cross-origin doivent autoriser l'en-tête baggage. Ajoutez "baggage" à Access-Control-Allow-Headers, ou définissez propagateTraceBaggage: false.
Échantillonnage déterministe L'échantillonnage est calculé à partir de l'ID de session + taux, non stocké. Cohérent entre les pages. Vérifiez si vous utilisez des taux d'échantillonnage différents sur différentes pages.
FID supprimé First Input Delay n'est plus collecté. Utilisez INP (Interaction to Next Paint) à la place.
Type de chargement de vue session_renewal Les vues renouvelées de session ont @view.loading_type:session_renewal au lieu de route_change. Mettez à jour les tableaux de bord/moniteurs filtrant sur @view.loading_type.
initiatorType de ressource document modifiée "initial_document" devient "navigation". La durée peut différer légèrement. Mettez à jour tout code inspectant performanceEntry de ressource document.
Les noms d'action peuvent changer La stratégie de traversée d'arbre est toujours utilisée (y compris Shadow DOM). Vérifiez si vous avez des moniteurs basés sur des noms d'action spécifiques.
Erreurs de requête annulées supprimées (Logs) Fetch/XHR abortés ne génèrent plus de logs d'erreur réseau. Aucune action nécessaire — réduit le bruit.
Logs requiert toujours le stockage de session Sans cookies ou localStorage, le SDK Logs ne démarrera pas. Utilisez sessionPersistence: 'memory' pour les environnements worker.
Session Replay : Change Records Nouveau format de sérialisation. Plus précis, moins de bande passante. Mettez à jour si vous dépendez du format de segment brut.
Les noms de chunk asynchrone sont préfixés avec datadog Par exemple, datadogRecorder-<hash>-datadog-rum.js, datadogProfiler-<hash>-datadog-rum.js. Mettez à jour les règles script-src de CSP ou les configurations de cache (autoriser datadog*-datadog-rum.js).

Étape 6 : Mettre à jour l'infrastructure

  • CSP :
    • Ajoutez crossorigin à script-src.
    • Mettez à jour les noms de chunk comme datadog*-datadog-rum.js (par exemple datadogRecorder, datadogProfiler).
    • Si vous avez supprimé usePciIntake, mettez à jour la CSP pour le domaine d'intake standard.
  • Cookies : Ajoutez _dd_s_v2 aux listes blanches de cookies. Le SDK migre automatiquement depuis _dd_s au premier chargement. Un retour à v6 démarre de nouvelles sessions.
  • CORS (si vous utilisez allowedTracingUrls) : Ajoutez "baggage" à Access-Control-Allow-Headers sur les origines tracées — ou définissez propagateTraceBaggage: false.
  • Support navigateur : Chrome 80+, Firefox 78+, Safari 14+ minimum (ES2020). ~0,048% moins de couverture.

Liste de vérification de vérification

Après la mise à niveau, confirmez :

  • [ ] SDK se charge sans erreurs de console
  • [ ] crossorigin="anonymous" sur toutes les balises script CDN
  • [ ] Aucune référence aux options supprimées dans la configuration init
  • [ ] Les enregistrements Session Replay fonctionnent (si utilisés)
  • [ ] Le traçage distribué fonctionne (pas d'erreurs CORS à partir de l'en-tête baggage)
  • [ ] Aucun cookie _dd_s restant après le premier chargement de page (devrait être _dd_s_v2)
  • [ ] Les noms d'action acceptables selon les nouveaux paramètres de confidentialité par défaut

Skills similaires

shopify-hydrogen
shopify / shopify-ai-toolkit

Implémenter des fonctionnalités Hydrogen Shopify via des recettes de cookbook prêtes à l'emploi.

319
web-coder
github / awesome-copilot

Coder des applications web performantes, accessibles et sécurisées selon les standards modernes.

33 040
zoom-apps-sdk
anthropics / knowledge-work-plugins

Créer des applications web intégrées au client Zoom avec le SDK officiel.

12 182
video-sdk/web
anthropics / knowledge-work-plugins

Développer des applications vidéo personnalisées dans le navigateur avec le SDK Zoom.

12 182
shopify-liquid
shopify / shopify-ai-toolkit

Développer des composants Liquid pour thèmes Shopify : sections, blocs et snippets.

319