@multiplayer-app/session-recorder-browser 1.2.6 → 1.2.7

package/README.md

@@ -49,6 +49,11 @@ yarn add @multiplayer-app/session-recorder-browser @opentelemetry/api
 ## Set up web client:
 
 ### Quick start
+
+Use the following code below to initialize and run the session recorder.
+
+### Initialize
+
 ```javascript
 import SessionRecorder from '@multiplayer-app/session-recorder-browser'
 
@@ -56,7 +61,7 @@ SessionRecorder.init({
   application: 'my-web-app',
   version: '1.0.0',
   environment: 'production',
-  apiKey: '<YOUR_FRONTEND_OTEL_TOKEN>',
+  apiKey: 'MULTIPLAYER_API_KEY' // note: replace with your Multiplayer API key
   // IMPORTANT: in order to propagate OTLP headers to a backend
   // domain(s) with a different origin, add backend domain(s) below.
   // e.g. if you serve your website from www.example.com
@@ -65,34 +70,24 @@ SessionRecorder.init({
   // propagateTraceHeaderCorsUrls: [new RegExp('https://api.example.com', 'i')],
 })
 
-
 // add any key value pairs which should be associated with a session
 SessionRecorder.setSessionAttributes({
   userId: '12345',
-  userName: 'Jane Doe',
+  userName: 'John Doe'
 })
-
-// optionally control via API (widget is enabled by default)
-// 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
 ```
 
 ### Advanced config
 
 ```javascript
-import SessionRecorder from '@multiplayer-app/debugger-browser'
+import SessionRecorder from '@multiplayer-app/session-recorder-browser'
 
 SessionRecorder.init({
   version: '1.0.0', // optional: version of your application
   application: 'my-app', // name of your application
   environment: 'production',
-  apiKey: 'your-api-key', // replace with your Multiplayer OTLP key
-  
+  apiKey: 'MULTIPLAYER_API_KEY', // note: replace with your Multiplayer API key
+
   apiBaseUrl: 'https://api.multiplayer.app', // override API base URL if needed
   exporterEndpoint: 'https://otlp.multiplayer.app', // override OTLP collector URL if needed
 
@@ -113,14 +108,14 @@ SessionRecorder.init({
   // configures what percentage (0.00-1.00) of OTLP data
   // should be sent through `exporters`
   sampleTraceRatio: 0,
-  
+
   // optional: exporters allow you to send
   // OTLP data to observability platforms
   exporters: [
     // example:
     // import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
     // new OTLPTraceExporter({
-    //   url: '<opentelemetry-collector-url>', 
+    //   url: '<opentelemetry-collector-url>',
     // })
   ],
 
@@ -148,7 +143,7 @@ SessionRecorder.init({
     maskTextClass: /sensitive|private/, // mask text in elements with these classes
     // CSS selector for text masking
     maskTextSelector: '.sensitive-data', // mask text in elements matching this selector
-    
+
     // custom masking functions
     maskInput: (text, element) => {
       if (element.classList.contains('credit-card')) {
@@ -172,7 +167,7 @@ SessionRecorder.init({
       }
       return payload
     },
-    
+
     isContentMaskingEnabled: true, // enable content masking in session recordings
     maskBody: (payload, span) => {
       // note: `payload` is already a copy of the original request/response content
@@ -208,26 +203,186 @@ SessionRecorder.init({
     headersToInclude: ['content-type', 'user-agent'],
     // list of headers to exclude from capturing
     headersToExclude: ['authorization', 'cookie']
-  },
+  }
+})
+```
 
-  // advanced options
+### Manual session recording
 
-  // allow Multiplayer Chrome to use post messages through the library
-  usePostMessageFallback: false
+Below is an example showing how to create a session recording in `MANUAL` mode. Manual session recordings stream and save all the data between calling `start` and `stop`.
+
+```javascript
+// add any key value pairs which should be associated with a session
+SessionRecorder.setSessionAttributes({
+  userId: '12345',
+  userName: 'John Doe'
 })
+// optionally control via API (widget is enabled by default)
+// 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
+```
 
+### Continuous session recording
+
+Below is an example showing how to create a session in `CONTINUOUS` mode. Continuous session recordings **stream** all the data received between calling `start` and `stop` - 
+but only **save** a rolling window data (90 seconds by default) when:
+
+- an exception or error occurs;
+- when `save` is called; or
+- programmatically, when the auto-save attribute is attached to a span.
+
+```javascript
 // add any key value pairs which should be associated with a session
 SessionRecorder.setSessionAttributes({
   userId: '12345',
   userName: 'John Doe'
 })
+// optionally control via API (widget is enabled by default)
+// 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
+
+SessionRecorder.save()
+
+SessionRecorder.stop('Finished session') // optional: pass reason for stopping the session
+```
+
+Continuous session recordings may also be saved from within any service or component involved in a trace by adding the attributes below to a span:
+
+```javascript
+import { trace, context } from "@opentelemetry/api"
+import SessionRecorder from "@multiplayer-app/session-recorder-browser"
+
+const activeContext = context.active()
+
+const activeSpan = trace.getSpan(activeContext)
+
+activeSpan.setAttribute(
+  SessionRecorder.ATTR_MULTIPLAYER_CONTINUOUS_SESSION_AUTO_SAVE,
+  true
+)
+activeSpan.setAttribute(
+  SessionRecorder.ATTR_MULTIPLAYER_CONTINUOUS_SESSION_AUTO_SAVE_REASON,
+  "Some reason"
+)
+
+```
+
+## Session Recorder for Next.js
+
+To integrate the MySessionRecorder component into your Next.js application, follow these steps:
+
+- Create a new file (e.g., MySessionRecorder.js or MySessionRecorder.tsx) in your root directory or a components directory.
+
+- Import the component
+
+In the newly created file, add the following code:
+
+```javascript
+'use client' // Mark as Client Component
+import { useEffect } from 'react'
+import SessionRecorder from '@multiplayer-app/session-recorder-browser'
+
+export default function MySessionRecorder() {
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      SessionRecorder.init({
+        version: '{YOUR_APPLICATION_VERSION}',
+        application: '{YOUR_APPLICATION_NAME}',
+        environment: '{YOUR_APPLICATION_ENVIRONMENT}',
+        apiKey: '{YOUR_API_KEY}',
+        recordCanvas: true, // Enable canvas recording
+        masking: {
+          maskAllInputs: true,
+          maskInputOptions: {
+            password: true,
+            email: false,
+            tel: false
+          }
+        }
+      })
+
+      SessionRecorder.setSessionAttributes({
+        userId: '{userId}',
+        userName: '{userName}'
+      })
+    }
+  }, [])
+
+  return null // No UI output needed
+}
+```
+
+Replace the placeholders with the actual information.
+
+Now, you can use the MySessionRecorder component in your application by adding it to your desired page or layout file:
+
+```javascript
+import MySessionRecorder from './MySessionRecorder' // Adjust the path as necessary
+
+export default function MyApp() {
+  return (
+    <>
+      <MySessionRecorder />
+      {/* Other components */}
+    </>
+  )
+}
+```
+
+## 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')
+})
+```
+
+If frontend sends api requests to two or more different domains put them to `propagateTraceHeaderCorsUrls` as array:
+
+```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')
+  ]
+})
 ```
 
 ### Framework notes
 
 - Next.js: initialize the browser SDK in a Client Component (see example in the browser README). Ensure it runs only in the browser.
 - CORS: when your frontend calls multiple API domains, set `propagateTraceHeaderCorsUrls` to match them so parent/child spans correlate across services.
+## Documentation
+
+For more details on how the Multiplayer Session Recorder integrates with your backend architecture and system auto-documentation, check out our [official documentation](https://www.multiplayer.app/docs/features/system-auto-documentation/).
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+This library is distributed under the [MIT License](./LICENSE).

package/dist/browser/index.js

@@ -25245,7 +25245,7 @@ const DEFAULT_MAX_HTTP_CAPTURING_PAYLOAD_SIZE = 100000;
 const SESSION_RESPONSE = 'multiplayer-debug-session-response';
 const CONTINUOUS_DEBUGGING_TIMEOUT = 60000; // 1 minutes
 const DEBUG_SESSION_MAX_DURATION_SECONDS = 10 * 60 + 30; // TODO: move to shared config otel core
-const PACKAGE_VERSION_EXPORT = "1.2.6" || 0;
+const PACKAGE_VERSION_EXPORT = "1.2.7" || 0;
 // Regex patterns for OpenTelemetry ignore URLs
 const OTEL_IGNORE_URLS = [
     // Traces endpoint
@@ -25663,8 +25663,6 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ });
 /* harmony import */ var _multiplayer_app_session_recorder_common__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! @multiplayer-app/session-recorder-common */ "../session-recorder-common/dist/esm/index-browser.js");
 
-
-const { schemify } = _multiplayer_app_session_recorder_common__WEBPACK_IMPORTED_MODULE_0__.SessionRecorderSdk;
 /**
  * Checks if the trace should be processed based on trace ID prefixes
  */
@@ -26798,6 +26796,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _index_scss__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(/*! ./index.scss */ "./src/index.scss");
 /* harmony import */ var _multiplayer_app_session_recorder_common__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(/*! @multiplayer-app/session-recorder-common */ "../session-recorder-common/dist/esm/index-browser.js");
 /* harmony import */ var _sessionWidget_buttonStateConfigs__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(/*! ./sessionWidget/buttonStateConfigs */ "./src/sessionWidget/buttonStateConfigs.ts");
+/* harmony import */ var lib0_observable__WEBPACK_IMPORTED_MODULE_13__ = __webpack_require__(/*! lib0/observable */ "../../node_modules/lib0/observable.js");
+
 
 
 
@@ -26811,7 +26811,10 @@ __webpack_require__.r(__webpack_exports__);
 
 
 
-class SessionRecorder {
+class SessionRecorder extends lib0_observable__WEBPACK_IMPORTED_MODULE_13__.Observable {
+    get isInitialized() {
+        return this._isInitialized;
+    }
     get sessionId() {
         return this._sessionId;
     }
@@ -26840,6 +26843,8 @@ class SessionRecorder {
         this._sessionWidget.updateState(this._sessionState, this.continuousRecording);
         _services_messaging_service__WEBPACK_IMPORTED_MODULE_8__["default"].sendMessage('state-change', this._sessionState);
         (0,_utils__WEBPACK_IMPORTED_MODULE_2__.setStoredItem)(_config__WEBPACK_IMPORTED_MODULE_4__.SESSION_STATE_PROP_NAME, state);
+        // Emit observable event to support React wrapper
+        this.emit('state-change', [this._sessionState || _types__WEBPACK_IMPORTED_MODULE_3__.SessionState.stopped, this.sessionType]);
     }
     get session() {
         return this._session;
@@ -26878,12 +26883,13 @@ class SessionRecorder {
      */
     constructor() {
         var _a;
-        this._isInitialized = false;
+        super();
         this._apiService = new _services_api_service__WEBPACK_IMPORTED_MODULE_9__.ApiService();
         this._tracer = new _otel__WEBPACK_IMPORTED_MODULE_0__.TracerBrowserSDK();
         this._recorder = new _rrweb__WEBPACK_IMPORTED_MODULE_1__.RecorderBrowserSDK();
         this._sessionWidget = new _sessionWidget__WEBPACK_IMPORTED_MODULE_7__.SessionWidget();
         this._startRequestController = null;
+        this._isInitialized = false;
         // Session ID and state are stored in localStorage
         this._sessionId = null;
         this._sessionType = _multiplayer_app_session_recorder_common__WEBPACK_IMPORTED_MODULE_11__.SessionType.PLAIN;
@@ -26935,6 +26941,8 @@ class SessionRecorder {
         this._registerSessionLimitReach();
         this._registerSessionAutoCreation();
         _services_messaging_service__WEBPACK_IMPORTED_MODULE_8__["default"].sendMessage('state-change', this.sessionState);
+        // Emit init observable event
+        this.emit('init', []);
     }
     /**
      * Save the continuous recording session
@@ -27220,6 +27228,7 @@ class SessionRecorder {
     _start() {
         var _a;
         this.sessionState = _types__WEBPACK_IMPORTED_MODULE_3__.SessionState.started;
+        this.sessionType = this.sessionType;
         this._tracer.start(this.sessionId, this.sessionType);
         this._recorder.start(this.sessionId, this.sessionType);
         if (this.session) {
@@ -28973,6 +28982,10 @@ const getNavigatorInfo = () => {
         cookiesEnabled,
         hardwareConcurrency,
         packageVersion,
+        // System type identifier (previously in system tags)
+        systemType: 'web',
+        // Platform identifier (previously in system tags)
+        platform: osInfo
     };
 };
 
@@ -30393,7 +30406,11 @@ __webpack_require__.r(__webpack_exports__);
 var SessionType;
 (function (SessionType) {
     SessionType["CONTINUOUS"] = "CONTINUOUS";
+    /**
+     * @deprecated Use MANUAL instead
+     */
     SessionType["PLAIN"] = "MANUAL";
+    SessionType["MANUAL"] = "MANUAL";
 })(SessionType || (SessionType = {}));
 //# sourceMappingURL=session-type.enum.js.map