Guide to Integrating TrueWatch Frontend RUM SDK in SSR Frameworks¶

This document provides guidance on how to correctly integrate the TrueWatch Frontend RUM SDK within SSR (Server-Side Rendering) frameworks, suitable for projects running on AWS Amplify or self-built Node SSR environments like Next.js, Nuxt, etc.

Core Principle¶

The TrueWatch RUM SDK can only be initialized in the browser environment, not during the server SSR phase.

Phase	Runtime Environment	Can SDK be Initialized?
SSR Rendering Phase	Node.js	❌ No
After Browser Hydration	Browser	✅ Yes

Therefore, we need to delay the SDK initialization logic until the client-side execution.

Installing the TrueWatch Frontend SDK¶

Install according to the actual package name you use, for example:

npm install @truewatchtech/browser-rum

Creating a "Client-Side Only" Initialization File¶

Create a new file:

/src/guanceRum.client.ts

import { datafluxRum } from '@truewatchtech/browser-rum'

export function initGuanceRum() {
  // Skip directly during SSR phase
  if (typeof window === 'undefined') return

  datafluxRum.init({
    applicationId: 'Your Application ID',
    datakitOrigin: '<DataKit Domain Name or IP>', // Required for DK method integration
    clientToken: 'clientToken', // Required for public OpenWay integration
    site: 'Public OpenWay URL', // Required for public OpenWay integration
    env: 'production',
    version: '1.0.0',
    sessionSampleRate: 100,
    sessionReplaySampleRate: 70,
    trackUserInteractions: true
    // Other optional configurations...
  })

  // Enable session replay recording
  datafluxRum.startSessionReplayRecording()
}

Key code:

if (typeof window === 'undefined') return

Used to ensure the SDK is not executed during the server rendering phase.

Integration in Next.js (Common for Amplify SSR)¶

Initialize in _app.tsx:

import { useEffect } from 'react'
import { initGuanceRum } from '../guanceRum.client'

export default function App({ Component, pageProps }) {
  useEffect(() => {
    initGuanceRum()
  }, [])

  return <Component {...pageProps} />
}

useEffect only runs in the browser and will not execute during the SSR phase.

Integration in Nuxt (Vue SSR)¶

Create a client-side plugin:

/plugins/guance-rum.client.js

import { datafluxRum } from '@truewatchtech/browser-rum'

export default () => {
  datafluxRum.init({
    applicationId: 'Your Application ID',
    datakitOrigin: '<DataKit Domain Name or IP>', // Required for DK method integration
    clientToken: 'clientToken', // Required for public OpenWay integration
    site: 'Public OpenWay URL', // Required for public OpenWay integration
    env: 'production',
    version: '1.0.0',
    sessionSampleRate: 100,
    sessionReplaySampleRate: 70,
    trackUserInteractions: true
    // Other optional configurations...
  })

  // Enable session replay recording
  datafluxRum.startSessionReplayRecording()
}

Register it in nuxt.config.js:

plugins: [{ src: '~/plugins/guance-rum.client.js', mode: 'client' }]

Notes¶

SDK initialization must be performed on the client-side.
Use useEffect or .client.js plugins.

By following the above methods, you can safely and stably integrate the TrueWatch Frontend RUM SDK in an SSR architecture.