Guide to Integrating Guance Frontend RUM SDK in SSR Frameworks¶

This document provides guidance on how to correctly integrate the Guance Frontend RUM SDK in SSR (Server-Side Rendering) frameworks, applicable to projects running on AWS Amplify or self-built Node SSR environments such as Next.js, Nuxt.js.

Core Principle¶

Guance RUM SDK can only be initialized in the browser environment and must not be executed during server SSR phase

Phase	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.

Install Guance Frontend SDK¶

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

npm install @cloudcare/browser-rum

Create a "Client-Only Execution" Initialization File¶

Create a new file:

/src/guanceRum.client.ts

import { datafluxRum } from '@cloudcare/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 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 does not execute during the SSR phase.

Nuxt (Vue SSR) Integration Method¶

Create a client plugin:

/plugins/guance-rum.client.js

import { datafluxRum } from '@cloudcare/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 in nuxt.config.js:

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

Notes¶

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

Through the above methods, you can safely and stably integrate the Guance Frontend RUM SDK in an SSR architecture.