フロントエンドフレームワークプラグインの導入¶
RUM SDK 3.3.6 以降、独立したフレームワークプラグインを使用して、フレームワークのルーティング View とフレームワークエラーを収集できます。 フレームワークプラグインは RUM メインパッケージとは独立しており、アプリケーションは実際に使用するプラグインのみをインストールすればよいです。
サポート範囲¶
| フレームワーク | サポートバージョン | ルーティング機能 | エラー機能 |
|---|---|---|---|
| React | React 18、19;React Router 6、7、8;TanStack Router 1.x | ルーティングテンプレートを使用して View を命名し、query または hash のみの変更は無視 | ErrorBoundary、addReactError() |
| Vue | Vue 2.7 + Vue Router 3;Vue 3 + Vue Router 4 | マッチしたルーティングテンプレートを使用して View を命名し、query のみの変更は無視 | Vue グローバルエラーハンドラー、addVueError() |
| Angular | Angular 15 ~ 22;RxJS 7 以上 | NavigationEnd 後に View を開始し、キャンセル、失敗、query または hash のみの変更は無視 |
Angular ErrorHandler、addAngularError() |
| Next.js | Next.js 13 以上、React 18 以上 | App Router と Pages Router をサポート | SSR フレームワークでの導入 を参照 |
| Nuxt | Nuxt 3、4;Vue 3;Vue Router 4 | Nuxt ファイルルーティングとクライアントナビゲーションをサポート | SSR フレームワークでの導入 を参照 |
バージョン要件
RUM メインパッケージのバージョンは、フレームワークプラグインのバージョン以上である必要があります。1つのアプリケーションでは、完全な RUM パッケージまたは軽量 RUM パッケージのいずれか1つだけを初期化できます。両方の RUM インスタンスを同時に初期化しないでください。
完全な RUM パッケージは、Session Replay と圧縮報告をサポートします。軽量 RUM パッケージにはこれらの機能は含まれません。 どちらの RUM パッケージでも、フレームワークプラグインを使用して View と Error を収集できます。
軽量 RUM パッケージを使用する場合は、RUM のインポートを置き換えるだけで、フレームワークプラグインの設定は変更しません:
以下の例では、パブリックネットワーク OpenWay の site と clientToken を使用しています。DataKit 直接接続を使用する場合は、これらの2つのパラメータを datakitOrigin に置き換え、両方の報告アドレスを同時に設定しないでください。
React¶
インストール¶
React Router¶
Router 統合を有効にするには、次の手順が必要です:
reactPlugin()でrouter: trueを設定します。- React Router のメジャーバージョンに一致するプラグインのサブパスから、Router 作成 API、
Routes、またはuseRoutesをインポートします。
以下の例は React Router 6 を使用しています:
import { RouterProvider } from "react-router-dom"
import { datafluxRum } from "@cloudcare/browser-rum"
import { reactPlugin } from "@cloudcare/browser-rum-react"
import {
createBrowserRouter,
} from "@cloudcare/browser-rum-react/react-router-v6"
const router = createBrowserRouter([
{ path: "/", element: <Home /> },
{ path: "/users/:id", element: <UserDetail /> },
])
datafluxRum.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_OPENWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
service: "web-react",
env: "production",
version: "1.0.0",
sessionSampleRate: 100,
plugins: [reactPlugin({ router: true })],
})
root.render(<RouterProvider router={router} />)
Router のバージョンに応じてエントリを選択します:
| Router | プラグインエントリ | プラグインエントリからエクスポートされる API |
|---|---|---|
| React Router 6 | @cloudcare/browser-rum-react/react-router-v6 |
createBrowserRouter、createHashRouter、createMemoryRouter、Routes、useRoutes |
| React Router 7 | @cloudcare/browser-rum-react/react-router-v7 |
同上 |
| React Router 8 | @cloudcare/browser-rum-react/react-router-v8 |
同上 |
| TanStack Router 1.x | @cloudcare/browser-rum-react/tanstack-router |
createRouter |
その他の Router API は、アプリケーションがインストールした Router パッケージからインポートします。フレームワークプラグインのメインエントリから Router wrapper をインポートしないでください。そうしないと、プラグインが Router のメジャーバージョンを区別できなくなります。
React エラー¶
アプリケーションのルートノードまたは重要なビジネス領域の外側で ErrorBoundary を使用します:
import { ErrorBoundary } from "@cloudcare/browser-rum-react"
root.render(
<ErrorBoundary
fallback={({ resetError }) => (
<button type="button" onClick={resetError}>リトライ</button>
)}
context={{ module: "checkout" }}
>
<App />
</ErrorBoundary>
)
既存の ErrorBoundary、React 19 のルートノードエラーコールバック、またはビジネスコードでエラーをキャッチしている場合は、addReactError(error, errorInfo, context) を呼び出します。React Error イベントには context.framework = react が含まれ、コンポーネントスタックが存在する場合は context.component_stack も含まれます。
Vue¶
インストール¶
Vue 3 と Vue Router 4¶
import { createApp } from "vue"
import { createWebHistory } from "vue-router"
import { datafluxRum } from "@cloudcare/browser-rum"
import { vuePlugin } from "@cloudcare/browser-rum-vue"
import {
createRouter,
} from "@cloudcare/browser-rum-vue/vue-router-v4"
const app = createApp(App)
const router = createRouter({
history: createWebHistory(),
routes: [
{ path: "/", component: Home },
{ path: "/users/:id", component: UserDetail },
],
})
datafluxRum.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_OPENWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
service: "web-vue",
env: "production",
version: "1.0.0",
sessionSampleRate: 100,
plugins: [vuePlugin({ app, router: true })],
})
app.use(router)
app.mount("#app")
app を渡すと、プラグインは Vue グローバルエラーハンドラーをインストールし、アプリケーションに既存の app.config.errorHandler も保持します。
Vue 2.7 と Vue Router 3¶
import Vue from "vue"
import { datafluxRum } from "@cloudcare/browser-rum"
import { vuePlugin } from "@cloudcare/browser-rum-vue"
import VueRouter from "@cloudcare/browser-rum-vue/vue-router-v3"
Vue.use(VueRouter)
const router = new VueRouter({ routes })
datafluxRum.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_OPENWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
plugins: [vuePlugin({ app: Vue, router: true })],
})
new Vue({ router, render: (h) => h(App) }).$mount("#app")
既存のカスタムエラーハンドラーがある場合は、addVueError(error, componentInstance, info, context) を呼び出すこともできます。Vue Error イベントには context.framework = vue が含まれ、可能な限りコンポーネント名とコンポーネントパスが記録されます。
Angular¶
インストール¶
Standalone アプリケーション¶
import { bootstrapApplication } from "@angular/platform-browser"
import { provideRouter } from "@angular/router"
import { datafluxRum } from "@cloudcare/browser-rum"
import { angularPlugin } from "@cloudcare/browser-rum-angular"
import {
provideRumErrorHandler,
provideRumRouter,
} from "@cloudcare/browser-rum-angular/providers"
datafluxRum.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_OPENWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
service: "web-angular",
env: "production",
version: "1.0.0",
sessionSampleRate: 100,
plugins: [angularPlugin({ router: true })],
})
bootstrapApplication(AppComponent, {
providers: [
provideRouter(routes),
provideRumRouter(),
provideRumErrorHandler(),
],
})
provideRumRouter() は、Angular Router が NavigationEnd を正常にトリガーした場合にのみ View を開始します。キャンセルまたは失敗したナビゲーションでは View は生成されません。provideRumErrorHandler() は Error を報告すると同時に、Angular のデフォルトのコンソールエラー処理動作を保持します。
既存のカスタム ErrorHandler がある場合は、addAngularError(error, context) を呼び出すことができます。既存のカスタム Router 統合がある場合は、trackAngularRouter(router) を呼び出すことができます。
View の命名とライフサイクル¶
フレームワークの Router 統合を有効にすると、プラグインが手動 View を引き継ぎます:
| シナリオ | 収集動作 |
|---|---|
| 初回ルーティングアクセス | 初期 View を作成 |
| pathname が変更され、ナビゲーションが成功 | 新しい View を作成 |
| query のみの変更 | 新しい View を作成しない |
| hash のみの変更 | React、Angular は新しい View を作成しない;Nuxt は hash ルーティングを追跡可能 |
| 動的ルーティング | /users/:id、/users/[id] などのテンプレート名を使用 |
| ジャンプのキャンセル、失敗、または新しいページが送信されない | View を作成しない |
Router プラグインとビジネスコード内の datafluxRum.startView() を同じルーティングに使用して追跡しないでください。重複した View が生成される可能性があります。
React、Vue、Angular プラグインはすべて getViewName コールバックをサポートしています。カスタム文字列を返すと、デフォルトのルーティングテンプレートを上書きできます。undefined を返すと、現在のルーティングの View 作成がスキップされます。
導入の確認¶
- ブラウザの開発者ツールを開き、Network タブで
/v1/write/rumをフィルタリングします。 - 動的ルーティングにアクセスします。例:
/users/1から/users/2へ遷移。 - View 名がルーティングテンプレート(具体的なユーザー ID ではない)のままであることを確認します。
- query のみを変更し、View が重複して作成されないことを確認します。
- フレームワークのレンダリングエラーをトリガーし、
type=errorが表示され、対応するcontext.frameworkが含まれていることを確認します。
よくある質問¶
router: true を有効にしても View が表示されない¶
Router 作成 API、Routes、または useRoutes が、現在の Router のメジャーバージョンに一致するプラグインのサブパスからインポートされていることを確認してください。プラグインを登録しただけで、元の Router 作成 API を引き続き使用している場合、プラグインは完全なルーティング状態を取得できません。
1回のルーティングジャンプで複数の View が生成される¶
アプリケーションで Router プラグインが重複して登録されていないこと、および同じルーティング変更に対して datafluxRum.startView() が追加で呼び出されていないことを確認してください。
動的ルーティングで多数の View 名が生成される¶
可能な限り Router テンプレートパスを使用してください。ルーティング設定から自動的に安定した名前を取得できない場合は、getViewName を使用してエンティティ ID を固定のビジネス名に統一マッピングします。