@obslysdk/browser v2.1.0

[](https://img.shields.io/npm/v/@obslysdk/browser)

🚀 Obsly SDK

Overview

Obsly offers an advanced observability platform for iOS, Android and Web Applications. Gain real-time insights, identify issues, and optimize your code for seamless performance.

Table of Contents

• Installation
• Configuration
• Developer Methods
  • Manage Sessions
  • Client identification
  • Application identification
  • Tag
  • Performance
  • Metrics
  • Rage Click
  • Application Context
  • SDK Control
  • Miscelaneous
• Help

Installation

Installing @obslysdk/browser

If you're using a package manager, simply install @obslysdk/browser:

npm install @obslysdk/browser

This library includes all the essential functionalities of the SDK.

Optional Libraries for Enhanced Functionality

Extend the capabilities of the Obsly SDK with these optional libraries. They provide specialized features and must be installed separately if you intend to use them.

Important: These libraries must be imported in your application's main entry point before you call the init method of the @obslysdk/browser SDK.

• @obslysdk/screenshot

  • Purpose: Enables capturing screenshots for visual feedback, rage click analysis, and attaching visual context to UI events. Refer to the Screenshot developer methods section for more details on its usage.

  • Installation:

    npm install @obslysdk/screenshot

  • NPM Link: npmjs.com/package/@obslysdk/screenshot

• @obslysdk/rules

  • Purpose: Allows for advanced rule-based event processing and conditional logic within the SDK.

  • Installation:

    npm install @obslysdk/rules

  • NPM Link: npmjs.com/package/@obslysdk/rules

Initialization

The SDK is initialized via the init function. There are two options to initialize the package, depending the context from where are you using the library.

Pure Javascript

Here is an example of how it should be started. This import allows the SDK to be executed right away the page renders. But it needs to extract "main.bundle.js" from the npm package:

index.html

<!-- Import the SDK (from npm package, cdn or local file) -->
<script src="browser.iife.js"></script>

<!-- Other optional libraries (These aren't included in the SDK package and need to be installed separately) -->
<!-- <script src="screenshot.iife.js"></script> -->
<!-- <script src="rules.iife.js"></script> -->

<!-- Initialize the SDK -->
<script>
  window.onload = () => {
    ObslySDK.init({
      ObslyKey: 'ObslyKey',
      instanceURL: 'https://api-url'
    })
  }
</script>

React

To initialize the SDK in a React application, we recommend the following approach:

obslysdk-init.ts

import { init } from '@obslysdk/browser'

// Other optional libraries (These aren't included in the SDK package and need to be installed separately)
// import "@obslysdk/screenshot"
// import "@obslysdk/rules"

// Initialize the SDK
init({
  ObslyKey: 'ObslyKey',
  instanceURL: 'https://api-url'
  // ... other parameters
})

Finally, import the SDK initialization in your main entry point:

main.tsx/jsx

import './obslysdk-init' // SDK initialization
import React from 'react'
// ... rest of imports

Configuration

SDK parameters

The SDK initialization method accepts various parameters to customize its behavior according to your application's needs. Below is a detailed description of each parameter:

Config structure

Code Example

ObslySDK.init({
  ObslyKey: 'ObslyKey',
  instanceURL: 'https://api-url',
  remoteConfigURL: 'https://api-url',
  proEnv: true,
  appVersion: '4.1.0',
  appName: 'myApp',
  config: {
    requestBlacklist: ['https://url1.com', 'https://url2.com'],
    requestHeadersWhitelist: [
      {
        url: 'https://api.example.com/sensitive/*',
        fromStatus: 400,
        toStatus: 599,
        headers: ['content-type', 'x-request-id'] // Only capture these specific headers
      }
    ],
    rateLimits: {
      base: {
        bucketSize: 20
      },
      error: {
        rejectWhenBucketFull: false
      }
    }
  }
})

Rate Limit Configuration

Rate limiting allows you to control the frequency of events being captured and sent to the server. You can configure rate limits for different event types:

Each rate limit configuration accepts the following parameters:

* Some events has some specific configurations to improve the performance and avoid the loss of events:

• bucketSize:
  • request: 20
• rejectWhenBucketFull:
  • console: true
  • error: true

Example of custom configuration:

const config = {
  rateLimits: {
    error: {
      interval: 2000, // If the bucket is full, process error events every 2 seconds to slow down the rate of events
      bucketSize: 15, // Allow up to 15 error. If you reach this limit, the bucket is full and we enter in the rate limit mode
      trailing: true, // Send trailing events after the rate limit period
      emptyBucketDelay: 2000, // Wait 2 seconds of stop sending 'error' events to empty the bucket
      rejectWhenBucketFull: false // Queue events when bucket is full
    },
    ui: {
      bucketSize: 20, // Allow up to 20 UI events. If you reach this limit, the bucket is full and we enter in the rate limit mode
      emptyBucketDelay: 2000 // Wait 2 seconds of stop sending 'ui' events to empty the bucket
      // The rest of the parameters are the same as the base configuration...
    }
  }
}

Request Headers Config

Requests Headers Config must be an Object with the following parameters:

Request Body Config

Requests Body Config must be an Object with the following parameters:

Wildcards

Wildcards provide flexible pattern matching in the SDK for both URLs and header names.

URL Wildcards

URL wildcards allow you to match a range of URLs with a single pattern:

• Simple Pattern: https://example.com/* matches URLs starting with https://example.com/, including any path or query string.
• Subdomain Pattern: https://*.example.com/* matches any subdomain of example.com (e.g., https://www.example.com/, https://api.example.com/).
• Domain Pattern: *.example.com/* matches example.com and all its subdomains, with any path.

{
  requestBlacklist: [
    'https://analytics.example.com/*', // Block all analytics endpoints
    'https://*.thirdparty.com/*' // Block all third-party domains
  ]
}

Header Name Wildcards

The same wildcard pattern matching can be applied to header names in RequestHeadersConfig:

• Contains Pattern: *content* matches any header containing 'content' (e.g., 'content-type', 'content-length', 'x-content-security').
• Prefix Pattern: content* matches headers starting with 'content' (e.g., 'content-type', 'content-encoding').
• Suffix Pattern: *type matches headers ending with 'type' (e.g., 'content-type', 'accept-type').

{
  url: 'https://api.example.com/*',
  fromStatus: 200,
  toStatus: 599,
  headers: [
    '*content*',        // Capture all headers containing 'content'
    'authorization',    // Capture the authorization header
    'x-*'               // Capture all headers starting with 'x-'
  ]
}

This wildcard functionality provides powerful flexibility for both URL matching and header filtering in your SDK configuration.

Webview Mode

Webview mode is used when the JavaScript SDK is initialized within a Webview that is being monitored by one of the native Obsly SDKs for Android or iOS. When this mode is enabled, all events will stop sending their own session metadata (USER, DEVICE, and APP) and instead, these values will be replaced with those from the native application.

Developer Methods

These are the following modules available to use from the SDK:

Manage Sessions

Session Types

Sessions can be of two types: Stateless or Stateful.

• Stateless Sessions: Each page reload or new tab is considered a new session.
• Stateful Sessions: The session is maintained and shared across tabs. The session ends only through a timeout or forced closure using the provided methods. Additionally, if an event occurs during a stateful session, the session's timeout will be refreshed to the expiration time defined.

Both the type of session (Stateless or Stateful) and the timeout duration are configurable through the SDK configuration with the parameters keepSessionOnRefresh and sessionMaxLengthMins.

Session Management Functions

This set of functions is dedicated to managing user sessions within your application. Sessions play a pivotal role in understanding user behavior. A new session is initialized on the first load of your web application. Sessions can be concluded in response to specific user actions, such as logging out or exiting the application.

Function Definitions

Description

• closeCurrentSession()

  • Parameters: None
  • Return Type: void
  • Async: Yes
  • Description: Closes the current session.

• createNewSession(customSessionID)

  • Parameters:
    • customSessionID: string (Required): The custom session ID to initiate the new session. If the ID is invalid, a new ID will be generated.
  • Return Type: void
  • Async: Yes
  • Description: Initiates a new Obsly session with a custom session ID. If the ID is invalid, a new ID will be generated.

Example

//Finishes the current Session and start automatically a new one
ObslySDK.closeCurrentSession()

//Finishes the current Session and start automatically a new one with a custom Session ID
ObslySDK.createNewSession('Custom Session ID')

Custom SessionID

There are two options to specify a custom Session ID:

• Via the init function, as a parameter.
• Using the createNewSession function after initialization.

Remember that if you are using a stateful session and you provide a custom Session ID, a new Session ID will be generated after the session expires.

Client identification

Client Identification involves associating unique identifiers with user sessions, enabling more precise tracking and personalized analysis.

Function Definitions

Description

• setUserID(userID)

  • Parameters:
    • userID: string (Required): The user ID to be set.
  • Return Type: void
  • Async: No
  • Description: Sets the user ID.

• setPersonID(personID)

  • Parameters:
    • personID: string (Required): The person ID to be set.
  • Return Type: void
  • Async: No
  • Description: Sets the person ID.

• setPassportID(passportID)

  • Parameters:
    • passportID: string (Required): The passport ID to be set.
  • Return Type: void
  • Async: No
  • Description: Sets the passport ID.

• setContractID(contractID)

  • Parameters:
    • contractID: string (Required): The contract ID to be set.
  • Return Type: void
  • Async: No
  • Description: Sets the contract ID.

Example

// Set user ID
ObslySDK.setUserID('User1')

Application identification

Obsly SDK provides modules for identifying application-specific information. It allows to identify the App Name and the Version.

Function Definitions

Description

• setAppName(appName)

  • Parameters:
    • appName: string (Required): The name of the application to be set.
  • Return Type: void
  • Async: No
  • Description: Sets the application name.

• setAppVersion(appVersion)

  • Parameters:
    • appVersion: string (Required): The version of the application to be set.
  • Return Type: void
  • Async: No
  • Description: Sets the application version.

Example

// Set App Name
ObslySDK.setAppName('MyNewApp')

// Set App Version
ObslySDK.setAppVersion('1.2.0')

Tag

The Tag functionality in the Obsly SDK is designed to enable the creation of custom key-value pairs, known as tags, that can be attached to user sessions or events. \ These tags can be strategically attached to user sessions or specific events within your application. This functionality is particularly advantageous for generating 'breadcrumbs', which serve as navigational aids in comprehensively understanding a user's interaction flow within the application.

Tag

A Tag is an object with the following structure:

• key: string (Required): A unique identifier for the tag. This should be a string that represents the tag's key.
• value: string (Required): The value associated with the tag's key. This should be a string representing the value.

{
  "key": "TAG1",
  "value": "VALUE1"
}

Function definitions

Description

• addTag(tags, category)

  • Parameters:
    • tags: Array<object> (Required): An array of key-value tag objects, each containing a key (string) and a value (string).
    • category: string (Required): A string representing the category for the tags.
  • Return Type: void
  • Async: Yes
  • Description: Creates a key-value tag with the provided tags array and associates it with the specified category.

Example

const tags = [
  {
    key: 'TAG1',
    value: 'VALUE1'
  },
  {
    key: 'TAG2',
    value: 'VALUE2'
  }
]

const category = 'NEW_CATEGORY'

ObslySDK.addTag(tags, category)

Screenshot

This feature is especially useful for visual analysis and debugging purposes, offering a snapshot view of the user's current application state.

Note: These functionalities are only available when the @obslysdk/screenshot library is installed. The library must be imported in your main entry point before executing the init method of the @obslysdk/browser SDK.

Function Definitions

Description

• addScreenshot()

  • Parameters: None
  • Return Type: void
  • Async: Yes
  • Description: Creates a browser screenshot event.

• getScreenshot()

  • Parameters: None
  • Return Type: Promise<string>
  • Async: Yes
  • Description: Returns a Base64 image string of a screenshot.

Example

const takeScreenshot = () => {
  ObslySDK.addScreenshot()
}

const screenImage = async () => {
  await ObslySDK.getScreenshot()
}

Performance

Metrics are a fundamental feature that allows for the precise measurement of performance within your application. \ They are primarily instrumented through performance events, which are designed to record the time elapsed between various stages or steps in a process.

Function Definitions

Description

• startTransaction(name, description, startNanoTime, autofinishWithStepsCount)

  • Parameters:
    • name: string (Required): The name of the performance event to start.
    • description: string (Optional): A description of the step.
    • startNanoTime: number (Optional): A number higher than 0 to set the start moment.
    • autofinishWithStepsCount: number (Optional): A number higher than 0 to automatically close the performance event after N steps.
  • Return Type: void
  • Async: Yes
  • Description: Starts a performance event with the given name and optional parameters for description, start time, and automatic finish after a specified number of steps.

• finishTransaction(name, updatedDescription)

  • Parameters:
    • name: string (Required): The name of the performance event to end.
    • updatedDescription: string (Optional): An updated description for the performance event.
  • Return Type: void
  • Async: Yes
  • Description: Ends a performance event with the specified name and optionally updates its description.

• startStep(transactionName, transactionName, description, startNanoTime)

  • Parameters:
    • transactionName: string (Required): The name of the performance event to which the step belongs.
    • stepName: string (Required): The name of the step.
    • description: string (Optional): A description of the step.
    • startNanoTime: number (Optional): A number higher than 0 to set the start moment of the step.
  • Return Type: void
  • Async: Yes
  • Description: Starts a step for an existing performance event with the specified name, step name, and optional parameters for description and start time.

• finishStep(name, transactionName, updatedDescription)

  • Parameters:
    • transactionName: string (Required): The name of the performance event to which the step belongs.
    • stepName: string (Required): The name of the step.
    • updatedDescription: string (Optional): An updated description for the step.
  • Return Type: void
  • Async: Yes
  • Description: Ends a step for an existing performance event and optionally updates the step's description.

Example

async function createMetric() {
  // Start a new Transaction
  await ObslySDK.startTransaction('DASHBOARD', 'Dashboard performance')

  // Create a new step Load Dashboard
  await ObslySDK.startStep('DASHBOARD', 'Load Dashboard')

  // End step on Load Dashboard
  await ObslySDK.finishStep('DASHBOARD', 'Load Dashboard')

  // Finally after all the steps, close the transaction
  await ObslySDK.endTransaction('DASHBOARD')
}

Metrics

Regarding metrics, we have 3 types of metrics:

• Counter: Any metric that increments over time.
• Gauge: For measuring fluctuating values.
• HistogramTimer: For measuring execution time.

To use the different types of metrics, we have the following methods:

Function Definitions

Description

• incCounter(key, fbl, operation, view, state)

  • Parameters:
    • key: string (Required): The key or name of the metric to increment.
    • fbl: string (Optional): The functional block label where the increment is being executed.
    • operation: string (Optional): The operation being performed.
    • view: string (Optional): The view where the increment is being executed.
    • state: string (Optional): The state of the operation, e.g., "OK" or "KO".
  • Return Type: void
  • Async: No
  • Description: Increments the value of a counter by 1 with the specified key. Optional parameters provide additional context.

• setGauge(key, value, fbl, operation, view, state)

  • Parameters:
    • key: string (Required): The key or name of the metric.
    • value: number (Required): The new value to set for the metric.
    • fbl: string (Optional): The functional block label where the gauge is being set.
    • operation: string (Optional): The operation being performed.
    • view: string (Optional): The view where the gauge is being set.
    • state: string (Optional): The state of the operation, e.g., "OK" or "KO".
  • Return Type: void
  • Async: No
  • Description: Sets the value of the metric with the given key and value. Optional parameters provide additional context.

• startHistogramTimer(key, fbl, operation, view)

  • Parameters:
    • key: string (Required): The key or name of the metric.
    • fbl: string (Optional): The functional block label where the timer is being started.
    • operation: string (Optional): The operation being performed.
    • view: string (Optional): The view where the timer is being started.
  • Return Type: void
  • Async: No
  • Description: Starts a HistogramTimer with the specified key. Optional parameters provide additional context.

• endHistogramTimer(key, fbl, operation, view, state)

  • Parameters:
    • key: string (Required): The key or name of the metric.
    • fbl: string (Optional): The functional block label where the timer is being ended.
    • operation: string (Optional): The operation being performed.
    • view: string (Optional): The view where the timer is being ended.
    • state: string (Optional): The state of the operation, e.g., "OK" or "KO".
  • Return Type: void
  • Async: No
  • Description: Ends a HistogramTimer with the specified key. Optional parameters provide additional context.

Example

async function fetchData(fbl, operation, view) {
  const key = "MY_FETCH_TIME";
  ObslySDK.startHistogramTimer(key, fbl, operation, view);
  let response = await fetch("https://api.example.com/data");
  ObslySDK.endHistogramTimer(key, fbl, operation, view);
  return await response.json();
}

async function onClick(fbl, operation, view) {
  const key = "CLICK_EVENT";
  ObslySDK.incCounter(key, fbl, operation, view);
  ...
}

async function onChange(value, fbl, operation, view) {
  const key = "MY_VALUE";
  ObslySDK.setGauge(key, value, fbl, operation, view)
}

const fbl = "FBL_EXAMPLE";
const operation = "OPERATION_EXAMPLE";
const view = "VIEW_EXAMPLE";

fetchData(fbl,operation,view);
onClick(fbl,operation,view);
onChange(2,fbl,operation,view);

Rage Click

Rage Click refers to a user behavior where multiple clicks are made in quick succession on a specific area of the screen or on a single component. This pattern often indicates that the user is experiencing frustration or difficulty with a particular part of the application, suggesting potential issues or malfunctions within that area. The rapid, repeated clicking is usually a sign that the user is attempting to interact with or resolve a problem that is not responding as expected.

By default, Rage Click is enabled and takes screenshots 25% of the time. These parameters can be configured during the initialization of the Obsly SDK See Configuration section.

Note: There may be elements in your application that you do not want to be treated as rage clicks, such as pagination buttons that are clicked in a very consecutive manner. In order to avoid false positives from rage clicks, you can put a tag on the component that you do not want to monitor.

The tag is data-ignore-rage-click, with value 'true'.

If you use data-ignore-rage-click-deep, also all its children will ignore Rage Click events.

Example

// Ignore only the parent
<div data-ignore-rage-click="true">
  <p>Here, I can detect rage click</p>
</div>


// Ignore the parent and all the children
<div data-ignore-rage-click-deep="true">
  <div id="Test"></div>
</div>

Application Context

In this application, there are three main concepts: Functional Blocks, Operations, and Views. Screens belong to Operations, and Operations belong to Functional Blocks, grouping views based on their functionality. This hierarchical structure helps organize and manage the application flow efficiently.

The context variables for Functional Block, Operation, and Screen are used to control and monitor application behavior. These variables are integrated into custom metrics tracking as well as Rage Click detection, ensuring comprehensive insights into user interactions and performance across different application contexts.

Funcion Definitions

Description

• setView(viewName)

  • Parameters:
    • viewName: string (Required): The name of the view to be set.
  • Return Type: void
  • Async: Yes
  • Description: Sets the current view name for the application.

• setOperation(operation)

  • Parameters:
    • operation: string (Required): The name of the operation to be set.
  • Return Type: void
  • Async: Yes
  • Description: Sets the current operation for the application.

• setFunctionalBlock(functionalBlock)

  • Parameters:
    • functionalBlock: string (Required): The name of the functional block to be set.
  • Return Type: void
  • Async: Yes
  • Description: Sets the current functional block for the application.

SDK Control

The following functions allow you to configure and manage the SDK's behavior and logging:

Function Definitions

Descriptions

• pauseTracker()

  • Parameters: None
  • Return Type: void
  • Async: Yes
  • Description: Pauses the sending of data to the server.

• resumeTracker()

  • Parameters: None
  • Return Type: void
  • Async: Yes
  • Description: Resumes sending data to the server.

• setLogLevel(level)

  • Parameters:
    • level: string (Required): The log level for the SDK Obsly. Allowed values are:
      • null
      • error
      • warn
      • log
  • Return Type: void
  • Async: Yes
  • Description: Sets the console log level for the SDK Obsly.

• setRequestsBlacklist(blacklist)

  • Parameters:
    • blacklist: string[] (Required): Array of string URLs to be blacklisted.
  • Return Type: void
  • Async: No
  • Description: Adds a blacklist of request URLs.

• getSessionInfo()

  • Parameters: None
  • Return Type: object
  • Async: Yes
  • Description: Gets session information.

Miscelaneous

This section includes various methods that do not fall into the previously defined categories.

Funcion Definitions

Description

• addFeedback(rating, message, image)

  • Parameters:
    • rating: number (Required): The rating for the feedback event.
    • message: string (Required): The message associated with the feedback.
    • image: string (Optional): The image related to the feedback, encoded in Base64 format.
  • Return Type: void
  • Async: No
  • Description: Adds a new feedback event with the specified rating, message, and Base64 encoded image.

• createErrorEvent(message, source, lineno, colno, error)

  • Parameters:
    • message: string (Required): The error message.
    • source: string (Required): The source file where the error occurred.
    • lineno: number (Required): The line number where the error occurred.
    • colno: number (Required): The column number where the error occurred.
    • error: Error (Required): The Error object containing additional information.
  • Return Type: void
  • Async: Yes
  • Description: Creates a custom error event with detailed information about the error that occurred. This can be used to manually report errors to Obsly for tracking and analysis.

Example

// Example of using addFeedback
ObslySDK.addFeedback(5, 'Great experience with the app!', null)

// Example of using createErrorEvent
try {
  // Some code that might throw an error
  throw new Error('Custom error for demonstration')
} catch (error) {
  ObslySDK.createErrorEvent(error.message, 'myScript.js', 123, 45, error)
}

Bridge

The Bridge functionality enables communication between the Obsly SDK and the native SDKs of the platforms (Android and iOS).

Configuration

The Bridge feature can be enabled via the configuration object during SDK initialization:

ObslySDK.init({
  ObslyKey: 'ObslyKey',
  instanceURL: 'https://api-url',
  config: {
    bridge: {
      enabled: true // Enable the Bridge feature
    }
  }
})

Note: The Bridge is not intended to be used for other purposes.

Getting Help

At Obsly, we are committed to providing exceptional support and ensuring that your experience with our SDK is as smooth and productive as possible. \ The most effective way to reach out to us with any questions, feedback, or support requests is via email. \ Send us your inquiries at info@obsly.tech

We value your input and are always eager to hear from our users. Your feedback helps us continually improve our SDK and services, ensuring they meet your needs and expectations.