SSR フレームワークでの統合¶

RUM SDK はブラウザ環境でのみ初期化でき、サーバーサイドレンダリング段階では実行できません。このページでは、Next.js と Nuxt の公式フレームワークプラグインによる統合方法を紹介します。

段階	実行環境	RUM を初期化するか
SSR、Server Component、Nitro 実行段階	Node.js	いいえ
Hydration およびクライアントルーティング段階	Browser	はい

フレームワークプラグインは、ブラウザの View、リソース、アクション、およびクライアントエラーを収集します。純粋なサーバーサイドリクエスト、Server Action、Nitro の処理プロセス、およびクライアントに渡されないサーバーエラーは、サーバーサイドの監視ソリューションを使用する必要があります。

バージョン要件

Next.js および Nuxt フレームワークプラグインは、RUM SDK 3.3.6 から提供されています。RUM メインパッケージのバージョンは、フレームワークプラグインのバージョン以上である必要があります。

以下の例では、パブリックネットワーク OpenWay の site と clientToken を使用しています。DataKit に直接接続する場合は、これらのパラメータを datakitOrigin に置き換え、両方のレポートアドレスを同時に設定しないでください。

Next.js¶

Next.js プラグインは、Next.js 13 以上、React 18 以上、および App Router と Pages Router をサポートしています。

インストール¶

npm install @cloudcare/browser-rum @cloudcare/browser-rum-nextjs

App Router：Next.js 15.3 以上¶

Next.js 15.3 以上では、instrumentation-client.js|ts をサポートしています。このファイルは hydration 前に実行されるため、ブラウザモニタリングを早期に初期化するのに適しています。

instrumentation-client.ts を作成します。プロジェクトが src ディレクトリを使用している場合は、ファイルを src/instrumentation-client.ts に配置します：

import { datafluxRum } from "@cloudcare/browser-rum"
import {
  nextjsPlugin,
  onRouterTransitionStart,
} from "@cloudcare/browser-rum-nextjs"

export { onRouterTransitionStart }

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-nextjs",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  plugins: [nextjsPlugin()],
})

クライアント Router tracker を作成します：

// app/rum-router-tracker.tsx
"use client"

import { RumNextjsAppRouter } from "@cloudcare/browser-rum-nextjs"

export function RumRouterTracker() {
  return <RumNextjsAppRouter />
}

ルート layout で一度レンダリングします：

// app/layout.tsx
import { RumRouterTracker } from "./rum-router-tracker"

export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN">
      <body>
        <RumRouterTracker />
        {children}
      </body>
    </html>
  )
}

onRouterTransitionStart() はナビゲーションターゲットを記録し、RumNextjsAppRouter は新しい pathname が実際にコミットされた後に View を作成します。ナビゲーションのキャンセル、失敗、またはレンダリングがコミットされなかった場合は、無効な View は作成されません。成功したリダイレクトが発生した場合、View は最終的にコミットされた pathname を使用します。

App Router：Next.js 13 ～ 15.2¶

これらのバージョンには instrumentation-client がないため、ルート layout にクライアント初期化コンポーネントを配置できます：

// app/rum-provider.tsx
"use client"

import { useEffect } from "react"
import { datafluxRum } from "@cloudcare/browser-rum"
import {
  nextjsPlugin,
  RumNextjsAppRouter,
} from "@cloudcare/browser-rum-nextjs"

let initialized = false

export function RumProvider() {
  useEffect(() => {
    if (initialized) return
    initialized = true

    datafluxRum.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-nextjs",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      plugins: [nextjsPlugin()],
    })
  }, [])

  return <RumNextjsAppRouter />
}

app/layout.tsx で <RumProvider /> をレンダリングします。この方法では、正常にコミットされた App Router ルートを収集できますが、初期化のタイミングは instrumentation-client よりも遅くなります。

Pages Router¶

pages/_app.tsx で初期化し、Pages Router tracker をレンダリングします：

import { useEffect } from "react"
import { datafluxRum } from "@cloudcare/browser-rum"
import {
  nextjsPlugin,
  RumNextjsPagesRouter,
} from "@cloudcare/browser-rum-nextjs"

let initialized = false

export default function App({ Component, pageProps }) {
  useEffect(() => {
    if (initialized) return
    initialized = true

    datafluxRum.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-nextjs",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      plugins: [nextjsPlugin()],
    })
  }, [])

  return (
    <>
      <RumNextjsPagesRouter />
      <Component {...pageProps} />
    </>
  )
}

Pages Router は router.pathname をテンプレート名として使用します。例えば、実際の URL /users/42 は /users/[id] に分類されます。routeChangeError、ナビゲーションのキャンセル、および query または hash のみの変更では、新しい View は作成されません。

Next.js View と Error¶

App Router は usePathname() と useParams() に基づいてファイルルーティングテンプレートを生成します：

実際の URL	View 名
`/`	`/`
`/users/42`	`/users/[id]`
`/docs/a/b`	`/docs/[...slug]`

安定した名前を自動生成できない場合は、getViewName を渡すことができます：

<RumNextjsAppRouter
  getViewName={(pathname, params) => (
    params.id ? "/users/[id]" : pathname
  )}
/>

App Router の error.tsx、global-error.tsx、またはビジネスエラーハンドラで addNextjsError() を呼び出します：

"use client"

import { useEffect } from "react"
import { addNextjsError } from "@cloudcare/browser-rum-nextjs"

export default function ErrorPage({ error, reset }) {
  useEffect(() => {
    addNextjsError(error, undefined, {
      route_boundary: "dashboard",
    })
  }, [error])

  return <button onClick={reset}>リトライ</button>
}

エラーオブジェクトに Next.js の digest が含まれている場合、プラグインはそれを Error コンテキストに書き込み、サーバーサイドログとの関連付けを容易にします。また、プラグインは ErrorBoundary を提供しており、クライアントの React サブツリーを保護するために使用できます。

Nuxt¶

Nuxt プラグインは、Nuxt 3、4、および Vue 3 と Vue Router 4 をサポートしています。

インストール¶

npm install @cloudcare/browser-rum @cloudcare/browser-rum-nuxt

クライアントプラグインの作成¶

プロジェクトの plugins ディレクトリに rum.client.ts を作成します。.client サフィックスにより、コードがブラウザでのみ実行されることが保証され、enforce: "pre" により RUM が早期にルーティングとエラー監視をインストールできるようになります。

import { datafluxRum } from "@cloudcare/browser-rum"
import { nuxtRumPlugin } from "@cloudcare/browser-rum-nuxt"

export default defineNuxtPlugin({
  name: "dataflux-rum",
  enforce: "pre",
  setup(nuxtApp) {
    datafluxRum.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-nuxt",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      plugins: [
        nuxtRumPlugin({
          nuxtApp,
          router: useRouter(),
        }),
      ],
    })
  },
})

Nuxt は plugins ディレクトリ直下のプラグインを自動的に登録するため、nuxt.config.ts に書き込む必要はありません。同じアプリケーションで Nuxt プラグインと Vue プラグインを同時に使用して同じ Router を追跡しないでください。

Nuxt View と Error¶

プラグインは Vue Router のパラメータパスを Nuxt のファイルルート名に変換します：

Vue Router パス	RUM View 名
`/users/:id`	`/users/[id]`
`/users/:id?`	`/users/[[id]]`
`/docs/:slug(.)`	`/docs/[...slug]`

成功した pathname ナビゲーションとハッシュルートは View を作成します。query のみの変更や失敗したナビゲーションでは View は作成されません。カスタム名が必要な場合は、nuxtRumPlugin() に getViewName(route) を渡します。

nuxtApp を渡すと、プラグインは Vue コンポーネントのエラーと Nuxt の app:error の両方を処理します。同じ Error オブジェクトが一度の伝播で両方のエラーチェーンに入った場合、1回のみレポートされ、アプリケーションの既存の Vue エラーハンドラは保持されます。

ビジネス側でエラーを積極的にキャッチする場合は、addNuxtError() を呼び出します：

import { addNuxtError } from "@cloudcare/browser-rum-nuxt"

try {
  await submitOrder()
} catch (error) {
  addNuxtError(error, {
    operation: "submit_order",
    module: "checkout",
  })
}

統合の確認¶

ブラウザの開発者ツールを開き、Network で /v1/write/rum をフィルタリングします。
初めてページにアクセスし、type=view が表示されることを確認します。
動的ルートにアクセスし、View が /users/[id] などのファイルルートテンプレートを使用していることを確認します。
query のみを変更し、View が重複して作成されていないことを確認します。
クライアントコンポーネントのエラーをトリガーし、type=error が表示され、context.framework = nextjs または context.framework = nuxt が含まれていることを確認します。

よくある質問¶

ビルド時に `window is not defined` が発生する¶

RUM の初期化がサーバーサイドモジュールに入りました。Next.js では instrumentation-client.ts または "use client" 付きの初期化コンポーネントを使用してください。Nuxt プラグインファイルは .client.ts または .client.js サフィックスを使用する必要があります。

Error はあるがフレームワーク View がない¶

Next.js では、現在の Router に対応する tracker をレンダリングする必要があります。Nuxt プラグインでは、router: useRouter() を渡す必要があります。同じアプリケーションで複数の Router tracker を混在させないでください。

1回の遷移で複数の View が作成される¶

アプリケーション全体に 1 つの tracker のみを配置し、同じナビゲーションに対して datafluxRum.startView() を呼び出さないでください。

SSR フレームワークでの統合¶

Next.js¶

インストール¶

App Router：Next.js 15.3 以上¶

App Router：Next.js 13 ～ 15.2¶

Pages Router¶

Next.js View と Error¶

Nuxt¶

インストール¶

クライアントプラグインの作成¶

Nuxt View と Error¶

統合の確認¶

よくある質問¶

ビルド時に window is not defined が発生する¶

Error はあるがフレームワーク View がない¶

1回の遷移で複数の View が作成される¶

このページは役に立ちましたか？ ×

ビルド時に `window is not defined` が発生する¶

このページは役に立ちましたか？