upgrade-browser-sdk-v7

Datadog Browser SDK を v7 にアップグレードする

v6 から v7 への体系的な移行ガイドです。手順 1〜6 を順番に実施してください。各手順には、対象コードを見つけるための検索パターンが含まれています。

Step 1: SDK のバージョンを更新する

CDN の設定 — スクリプトの src URL を更新します。

v6 のパターン	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

us1 はご利用のサイトに置き換えます：eu1、us3、us5、ap1、ap2。US1-FED の場合、サイトのプレフィックスがないフラットなパターンを使用します：datadog-rum-v7.js、datadog-logs-v7.js、datadog-rum-slim-v7.js。

検索：grep -r "datadoghq-browser-agent.com.*v6" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"

npm の設定 — package.json の依存関係を更新します。

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

その後、パッケージマネージャー（npm install、yarn install など）を実行して、再ビルドします。

フレームワーク連携機能も v7 にアップグレードします：@datadog/browser-rum-react、@datadog/browser-rum-angular、@datadog/browser-rum-vue、@datadog/browser-rum-nextjs。

検索：grep -r "@datadog/browser-" --include="package.json" .

Step 2: crossorigin="anonymous" を追加する（CDN のみ）

v7 の CDN バンドルでは ESM の動的インポートを使用します。SDK を読み込む すべての <script> タグに crossorigin="anonymous" を指定する必要があります。

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

動的に作成される スクリプト要素の場合：

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'

検索：grep -rn "datadoghq-browser-agent" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"

一致した箇所すべてで、crossorigin 属性（HTML）または .crossOrigin プロパティ（JS）があることを確認してください。

Step 3: 非推奨のオプションを削除する

初期化呼び出しを検索して、以下のオプションを置き換えます。

Core から削除された項目（RUM と Logs の両方に影響）

オプション	対応
betaEncodeCookieOptions	削除します。Cookie のエンコードは常に有効です。
allowFallbackToLocalStorage	sessionPersistence: ['cookie', 'local-storage'] に置き換えます。

RUM から削除された項目

オプション	対応
trackBfcacheViews	削除します。BFCache のビューは常に追跡されます。
trackEarlyRequests	削除します。早期リクエストは常に収集されます。
betaTrackActionsInShadowDom	削除します。Shadow DOM のアクション追跡は常に有効です。

Logs から削除された項目

オプション	対応
usePciIntake	削除します。標準のインテークは PCI に準拠するようになりました。PCI 専用のドメインを許可リストに登録していた場合は、CSP を更新してください。

検索：grep -rn 'betaEncodeCookieOptions\|allowFallbackToLocalStorage\|trackBfcacheViews\|trackEarlyRequests\|betaTrackActionsInShadowDom\|usePciIntake' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Step 4: 変更された API を更新する

4a. forwardErrorsToLogs + forwardConsoleLogs（Logs）

これらは独立したオプションになりました。v6 では、forwardErrorsToLogs: true に副作用があり、console.error() の呼び出しも Logs に転送されていました。v7 では、この副作用がなくなりました。

• forwardErrorsToLogs — 未処理エラー（捕捉されなかった例外、未処理の拒否）とネットワークエラーを Logs に転送するかどうかを制御します。変更しないでください。
• forwardConsoleLogs — console.error() の呼び出しを Logs に転送するかどうかを制御します。v6 の副作用を復元するには、ここに 'error' を追加します。

forwardErrorsToLogs が true または省略されている場合に限り、forwardConsoleLogs: ['error'] を追加してください — v6 では、この副作用はこのオプションが有効な場合（明示的に指定されている場合、またはデフォルトの場合）にのみ適用されていました。forwardErrorsToLogs: false の場合、復元する副作用はありません。変更しないでください。

// 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']
})

forwardErrorsToLogs を forwardConsoleLogs に置き換えないでください — これらは異なるものを制御します。

明示的な設定を検索します：grep -rn "forwardErrorsToLogs" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

デフォルトに依存している可能性のある Logs の初期化呼び出しも検索します（v6 では forwardErrorsToLogs のデフォルトが true なので、省略しても副作用がありました）：grep -rn "DD_LOGS\.init\|datadogLogs\.init" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

forwardErrorsToLogs が true または省略されていて、forwardConsoleLogs に 'error' も 'all' も含まれていない Logs の初期化呼び出しでは、v6 の動作を維持するために 'error' を追加してください。

4b. startDurationVital / stopDurationVital（RUM）

DurationVitalReference オブジェクトは vitalKey 文字列に置き換えられます。startDurationVital は void を返すようになりました — v7 API は実行して結果を待たない方式です。必要なのは vital 名の文字列だけです。

// 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' })

CDN／プレーン JS のプロジェクトでは、これは気づかないうちに不具合を引き起こします。 TypeScript では型エラーとして検出されますが、プレーン JS では検出されません。ref は undefined になり、stopDurationVital(undefined) は何もしません。そのため、vital は開始しても停止せず、イベントが送信されません。

手順 1 — startDurationVital／stopDurationVital の使用箇所をすべて検索します（CDN と npm の両方のパターン、すべてのファイル形式が対象です）：

grep -rn 'startDurationVital\|stopDurationVital\|DurationVitalReference' \
  --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" \
  --include="*.html" --include="*.svelte" --include="*.vue"

手順 2 — 戻り値を受け取っている変数をすべて検索します（これが不具合の原因です）：

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"

該当する箇所ごとに、変数への代入を削除し、対応する stopDurationVital 呼び出しで、その変数を vital 名の文字列に直接置き換えてください。

手順 3 — SDK がユーティリティでラップされている場合（例：startTiming／stopTiming）：

1. ラッパーを更新します — vitalKey を startDurationVital に渡し、何も返さないようにします。
2. ラッパーの戻り値を受け取っている呼び出し元を検索します：

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. 代入を削除し、停止の呼び出しに vital 名の文字列を直接渡すように更新します：

// Caller — before
var ref = startTiming('checkout_flow')
stopTiming(ref) // undefined in v7 → vital never stops

// Caller — after
startTiming('checkout_flow')
stopTiming('checkout_flow')

4c. プラグイン API：strategy の削除（RUM）

プラグイン API から strategy フィールドが削除されました。@datadog/browser-rum-react やその他のプラグイン連携を使用している場合は、v7 にアップグレードしてください。

検索：grep -rn "strategy" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"（プラグイン定義を探します）

Step 5：動作の変更を確認する（コードの変更は不要ですが、対応が必要な場合があります）

これらはデフォルトの変更です — コードが壊れることはありませんが、動作が v6 から変わります。

変更	影響	必要に応じた対応
defaultPrivacyLevel のデフォルト値が "mask-user-input" に変更（以前は "mask"）	初期状態のマスキングが緩和されます。ユーザー入力のみがマスキングされます。	完全なマスキングを維持するには、defaultPrivacyLevel: "mask" を設定してください。
enablePrivacyForActionName のデフォルト値が true に変更	アクション名は innerText ではなく textContent から取得されるため、CSS の text-transform は適用されなくなりました。style="text-transform: capitalize" が設定され、生テキストが "audio" のボタンは、v6 では "Audio"、v7 では "audio" になります。プライバシーレベルに応じて、名前がマスキングされる場合もあります。**注：**これを false に設定しても、CSS を考慮した抽出には戻りません。v7 では常に textContent が使用されます。	表示名が CSS 変換に依存していた要素に data-dd-action-name 属性を追加するか、モニターが生テキスト値に一致するよう更新してください。アノテーションベースの制御には、Datadog build plugin を使用してください。
propagateTraceBaggage のデフォルト値が true に変更	CORS：クロスオリジン API では baggage ヘッダーを許可する必要があります。	Access-Control-Allow-Headers に "baggage" を追加するか、propagateTraceBaggage: false を設定してください。
決定的サンプリング	サンプリングは保存されず、セッション ID とレートから算出されます。ページ間で一貫性があります。	ページごとに異なるサンプルレートを使用している場合は、確認してください。
FID の削除	First Input Delay は収集されなくなりました。	代わりに INP（Interaction to Next Paint）を使用してください。
session_renewal ビューの読み込みタイプ	セッションが更新されたビューでは、@view.loading_type:session_renewal が設定されます（以前は route_change）。	@view.loading_type でフィルタリングしているダッシュボードやモニターを更新してください。
ドキュメントリソースの initiatorType が変更	"initial_document" が "navigation" に変更されます。所要時間が若干異なる場合があります。	ドキュメントリソースの performanceEntry を調べるコードを更新してください。
アクション名が変更される場合がある	v7 では Shadow DOM を含め、常にツリーウォーカーと textContent が使用されます。enablePrivacyForActionName の設定にかかわらず、CSS の text-transform は反映されません。表示上変換された名前を大文字と小文字を区別してフィルタリングするモニターは、動作しなくなる場合があります。	該当する要素に data-dd-action-name 属性を追加するか、モニターが生テキスト値に一致するよう更新してください。
キャンセルされたリクエストのエラーを削除（Logs）	中断された fetch/XHR では、ネットワークエラーログが生成されなくなりました。	対応は不要です。ノイズが減少します。
Logs でセッションストレージが常に必要に	Cookie または localStorage がない場合、Logs SDK は起動しません。	ワーカー環境では sessionPersistence: 'memory' を使用してください。
Session Replay：変更レコード	シリアライズ形式が新しくなりました。より正確になり、帯域幅も削減されます。	生のセグメント形式に依存している場合は、更新してください。
非同期チャンク名に datadog が付加	例：datadogRecorder-<hash>-datadog-rum.js、datadogProfiler-<hash>-datadog-rum.js。	CSP の script-src ルールまたはキャッシュ設定を更新してください（datadog*-datadog-rum.js を許可）。

Step 6: インフラストラクチャを更新する

• CSP：
  • script-src に crossorigin を追加します。
  • datadogRecorder や datadogProfiler など、datadog*-datadog-rum.js のようなチャンク名を更新します。
  • usePciIntake を削除した場合は、標準のインテークドメインに合わせて CSP を更新します。
• Cookie：Cookie の許可リストに _dd_s_v2 を追加します。SDK は初回読み込み時に _dd_s から自動的に移行します。v6 にロールバックすると、新しいセッションが開始されます。
• CORS：トレーシング設定を検索します：grep -rn "allowedTracingUrls\|propagateTraceBaggage" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"。allowedTracingUrls が設定されていて、propagateTraceBaggage: false が明示的に設定されていないプロジェクトでは、トレース対象のオリジンに対する既存の Access-Control-Allow-Headers に "baggage" を追加するか、propagateTraceBaggage: false を設定して無効にします。
• ブラウザーのサポート：最低要件は Chrome 80 以降、Firefox 78 以降、Safari 14 以降です（ES2020）。カバー率は約 0.048% 低下します。

よくある間違い

間違い	問題	修正
forwardErrorsToLogs: true を forwardConsoleLogs: ['error'] に置き換える	未処理エラー（捕捉されない例外、未処理の拒否）が Logs に転送されなくなります	forwardErrorsToLogs: true は変更せずに残し、併せて forwardConsoleLogs: ['error'] を追加します。これらは異なる機能を制御します
startDurationVital のラッパーを更新し、呼び出し側を更新しない	呼び出し側が古い ref 変数（現在は undefined）を stopDurationVital に渡すため、Vital が停止せず、イベントも出力されません	ラッパーを更新した後、戻り値を取得する呼び出し箇所をすべて検索し、停止呼び出しに Vital 名の文字列を直接渡すよう更新します
stopDurationVital に vitalKey オプションを指定しない	v7 の stopDurationVital では、停止する Vital を特定するために { vitalKey: string } が必須です	startDurationVital で使用した文字列と同じものを渡します：stopDurationVital('name', { vitalKey: 'name' })
ref ベースの Vital を CDN／プレーンな JS ファイルで確認しない	TypeScript のプロジェクトでは型エラーとして表面化しますが、プレーンな JS では気付かないまま動作しなくなります	Step 2 の grep を明示的に実行します。型エラーだけに頼って該当箇所をすべて見つけようとしないでください

検証チェックリスト

アップグレード後、次の項目を確認してください：

• SDK がコンソールエラーなしで読み込まれる
• すべての CDN スクリプトタグに crossorigin="anonymous" がある
• 初期化設定に削除済みオプションへの参照がない
• セッションリプレイの記録が機能している（使用している場合）
• 分散トレーシングが機能している（baggage ヘッダーによる CORS エラーがない）
• 初回のページ読み込み後に _dd_s Cookie が残っていない（_dd_s_v2 になっている）
• 新しいプライバシーのデフォルト設定でアクション名に問題がない
• startDurationVital（またはそのラッパー）の戻り値を格納する変数がない。すべての停止呼び出しで Vital 名の文字列を直接使用している