@multiplayer-app/session-recorder-browser 1.2.27 → 1.2.28

package/README.md

@@ -221,10 +221,37 @@ SessionRecorder.setSessionAttributes({
 // if you're not using widget (see: `showWidget: true/false`)
 // then you can programatically control the session recorder
 // by using the methods below
-SessionRecorder.start()
-SessionRecorder.pause()
-SessionRecorder.resume()
-SessionRecorder.stop('Finished session') // optional: pass reason for stopping the session
+
+// Option A: fire-and-forget (simple)
+// SessionRecorder.start()
+// ... later ...
+// SessionRecorder.stop('Finished session')
+
+// Option B: wire up your own UI controls
+const startButton = document.getElementById('start')
+const pauseButton = document.getElementById('pause')
+const resumeButton = document.getElementById('resume')
+const stopButton = document.getElementById('stop')
+
+startButton?.addEventListener('click', () => {
+  SessionRecorder.start()
+})
+
+startContinuousButton?.addEventListener('click', () => {
+  SessionRecorder.start(SessionType.CONTINUOUS)
+})
+
+pauseButton?.addEventListener('click', () => {
+  SessionRecorder.pause()
+})
+
+resumeButton?.addEventListener('click', () => {
+  SessionRecorder.resume()
+})
+
+stopButton?.addEventListener('click', () => {
+  SessionRecorder.stop('Finished session') // optional reason
+})
 ```
 
 ### Continuous session recording
@@ -246,17 +273,28 @@ SessionRecorder.setSessionAttributes({
 // if you're not using widget (see: `showWidget: true/false`)
 // then you can programatically control the session recorder
 // by using the methods below
-SessionRecorder.start(SessionType.CONTINUOUS)
-
-// do something here
-
-SessionRecorder.save()
-
-// do something here
+// Option A: fire-and-forget (simple)
+// SessionRecorder.start(SessionType.CONTINUOUS)
+// ... later ...
+// SessionRecorder.save()
+// ... later ...
+// SessionRecorder.stop('Finished session')
+// Option B: wire up your own UI controls
+const startContinuousButton = document.getElementById('start-continuous')
+const saveButton = document.getElementById('save')
+const stopButton = document.getElementById('stop')
+
+startContinuousButton?.addEventListener('click', () => {
+  SessionRecorder.start(SessionType.CONTINUOUS)
+})
 
-SessionRecorder.save()
+saveButton?.addEventListener('click', () => {
+  SessionRecorder.save()
+})
 
-SessionRecorder.stop('Finished session') // optional: pass reason for stopping the session
+stopButton?.addEventListener('click', () => {
+  SessionRecorder.stop('Finished session') // optional reason
+})
 ```
 
 ### Capture exceptions
@@ -361,20 +399,64 @@ export default function MyApp() {
 }
 ```
 
+### Next.js 15.3+ (App Router) — instrumentation-client.ts
+
+On Next.js 15.3+ you can initialize the Session Recorder as early as possible with `src/instrumentation-client.ts|js`, which runs before hydration. You can also export `onRouterTransitionStart` to observe navigation. See the official docs: [instrumentation-client.ts](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation-client).
+
+1. Create `app/instrumentation-client.ts|js`:
+
+```ts
+import SessionRecorder from '@multiplayer-app/session-recorder-browser'
+
+// Initialize as early as possible (before hydration)
+try {
+  SessionRecorder.init({
+    application: 'my-next-app',
+    version: '1.0.0',
+    environment: process.env.NEXT_PUBLIC_ENVIRONMENT ?? 'production',
+    apiKey: process.env.NEXT_PUBLIC_MULTIPLAYER_API_KEY!,
+    showWidget: true,
+    // If your APIs are on different origins, add them so OTLP headers are propagated
+    // format: string | RegExp | Array
+    propagateTraceHeaderCorsUrls: [new RegExp('https://api.example.com', 'i')]
+  })
+} catch (error) {
+  // Keep instrumentation resilient
+  console.warn('[SessionRecorder] init failed in instrumentation-client:', error)
+}
+
+// Optional: Next.js will call this when navigation begins
+export function onRouterTransitionStart(url: string, navigationType: 'push' | 'replace' | 'traverse') {
+  try {
+    SessionRecorder.navigation.record({
+      path: url || '/',
+      navigationType,
+      framework: 'nextjs',
+      source: 'instrumentation-client'
+    })
+  } catch (error) {
+    console.warn('[SessionRecorder] navigation record failed:', error)
+  }
+}
+```
+
 ## Note
 
 If frontend domain doesn't match to backend one, set backend domain to `propagateTraceHeaderCorsUrls` parameter:
 
 ```javascript
 import SessionRecorder from '@multiplayer-app/session-recorder-browser'
-
-SessionRecorder.init({
-  version: '{YOUR_APPLICATION_VERSION}',
-  application: '{YOUR_APPLICATION_NAME}',
-  environment: '{YOUR_APPLICATION_ENVIRONMENT}',
-  apiKey: '{YOUR_API_KEY}',
-  propagateTraceHeaderCorsUrls: new RegExp(`https://your.backend.api.domain`, 'i')
-})
+try {
+  SessionRecorder.init({
+    application: 'my-next-app',
+    version: '1.0.0',
+    environment: process.env.NEXT_PUBLIC_ENVIRONMENT ?? 'production',
+    apiKey: process.env.NEXT_PUBLIC_MULTIPLAYER_API_KEY!,
+    propagateTraceHeaderCorsUrls: new RegExp(`https://your.backend.api.domain`, 'i')
+  })
+} catch (error) {
+  console.warn('[SessionRecorder] init failed:', error)
+}
 ```
 
 If frontend sends api requests to two or more different domains put them to `propagateTraceHeaderCorsUrls` as array:
@@ -382,16 +464,17 @@ If frontend sends api requests to two or more different domains put them to `pro
 ```javascript
 import SessionRecorder from '@multiplayer-app/session-recorder-browser'
 
-SessionRecorder.init({
-  version: '{YOUR_APPLICATION_VERSION}',
-  application: '{YOUR_APPLICATION_NAME}',
-  environment: '{YOUR_APPLICATION_ENVIRONMENT}',
-  apiKey: '{YOUR_API_KEY}',
-  propagateTraceHeaderCorsUrls: [
-    new RegExp(`https://your.backend.api.domain`, 'i'),
-    new RegExp(`https://another.backend.api.domain`, 'i')
-  ]
-})
+try {
+  SessionRecorder.init({
+    // ... other config ...
+    propagateTraceHeaderCorsUrls: [
+      new RegExp(`https://your.backend.api.domain`, 'i'),
+      new RegExp(`https://another.backend.api.domain`, 'i')
+    ]
+  })
+} catch (error) {
+  console.warn('[SessionRecorder] init failed:', error)
+}
 ```
 
 ### Framework notes