@perceptr/web-sdk NPM

Perceptr Web SDK

License

Description

Perceptr Web SDK is a powerful, lightweight session recording and monitoring tool for web applications. It captures user interactions, network requests, console logs, and more to provide comprehensive insights into user behavior and application performance.

Summary

This SDK enables developers to:

📹 Session Recording: Capture user interactions, DOM changes, and

page navigation

🌐 Network Monitoring: Track API calls, response times, and errors
📊 Console Logging: Record console activity for debugging
🔒 Privacy-Focused: Built-in data sanitization for sensitive

information

🧩 Framework Agnostic: Works with any JavaScript framework or

vanilla JS

🚀 Performance Optimized: Minimal impact on application performance

The SDK is designed to be lightweight, privacy-focused, and easy to integrate into any web application.

Installation

# npm
npm  install  @perceptr/web-sdk

# yarn
yarn  add  @perceptr/web-sdk

# pnpm

pnpm  add  @perceptr/web-sdk

API Reference

Perceptr Object

The default export is a singleton instance with the following methods:

Method	Description	Parameters
`init(config)`	Initialize the SDK	`config: CoreConfig`
`start()`	Start recording the session	Returns `Promise<void>`
`stop()`	Stop recording and return session data	Returns `Promise<void>`
`pause()`	Temporarily pause recording	None
`resume()`	Resume a paused recording	None
`identify(distinctId, traits)`	Associate the session with a user	`distinctId: string, traits?: Record<string, any>` Returns `Promise<void>`

Importing

import  Perceptr, { CoreConfig, UserIdentity } from  "@perceptr/web-sdk";

Perceptr Methods

`init(config: CoreConfig): void`

Initializes the SDK with the provided configuration.

Perceptr.init({

projectId: 'your-project-id',

debug: true

});

`start(): void`

Starts recording the user session.

await Perceptr.start();

`stop(): Promise<void>`

Stops the recording and returns the session data.

await Perceptr.stop();

`pause(): void`

Temporarily pauses the recording.

Perceptr.pause();

`resume(): void`

Resumes a paused recording.

Perceptr.resume();

`identify(distinctId: string, traits?: Record<string, any>): void`

Associates the current session with a user identity.

await Perceptr.identify('user-123', {

email: 'user@example.com',

name: 'John Doe',

plan: 'premium'

});

Type Definitions

CoreConfig

interface  CoreConfig {

projectId: string; // Required: Your Perceptr project ID

debug?: boolean; // Optional: Enable debug logging

session?: SessionConfig; // Optional: Session recording configuration

network?: NetworkMonitorConfig; // Optional: Network monitoring configuration

metadata?: Record<string, any>; // Optional: Custom metadata to include with sessions

userIdentity?: UserIdentity; // Optional: Initial user identity

}

UserIdentity

interface  UserIdentity {

distinctId: string; // Required: Unique identifier for the user

email?: string; // Optional: User's email

name?: string; // Optional: User's name

[key: string]: any; // Optional: Any additional user properties

}

Framework Integration Examples

Vanilla JavaScript

<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="UTF-8">

<title>Perceptr Demo</title>

</head>

<body>

<h1>Perceptr SDK Demo</h1>

<form id="login-form">

<input type="text" id="user-id" placeholder="User ID">

<input type="email" id="email" placeholder="Email">

<button type="submit">Login</button>

</form>

  

<script type="module">

import Perceptr from 'https://cdn.jsdelivr.net/npm/@perceptr/web-sdk/dist/esm/index.js';

// Initialize when the page loads

document.addEventListener('DOMContentLoaded', async() => {

Perceptr.init({

projectId: 'your-project-id'

});

await Perceptr.start();

// Optional: Identify user after login

document.getElementById('login-form').addEventListener('submit', (e) => {

e.preventDefault();

const userId = document.getElementById('user-id').value;

await Perceptr.identify(userId, {

email: document.getElementById('email').value

});

alert('User identified!');

});

// Clean up when the page is unloaded

window.addEventListener('beforeunload', () => {

Perceptr.stop();

});

});

</script>

</body>

</html>

React

// src/App.jsx

import { useEffect } from  'react';

import  Perceptr  from  '@perceptr/web-sdk';

import  LoginForm  from  './components/LoginForm';

  

function  App() {

useEffect(() => {
    const init = async () => {
// Initialize once when the app loads

Perceptr.init({

projectId: 'your-project-id'

});

await Perceptr.start();
    }
    init();
// Clean up on unmount

return () => {

 Perceptr.stop();

};

}, []);

const  handleLogin  = async (userId, email) => {

await Perceptr.identify(userId, {

email,

loginTime: new  Date().toISOString()

});

};

return (

<div  className="App">

<h1>Perceptr SDK Demo</h1>

<LoginForm  onLogin={handleLogin} />

</div>

);

}

  

export  default  App;

  

// src/components/LoginForm.jsx

import { useState } from  'react';

  

function  LoginForm({ onLogin }) {

const [userId, setUserId] =  useState('');

const [email, setEmail] =  useState('');

const  handleSubmit  = (e) => {

e.preventDefault();

onLogin(userId, email);

alert('User identified!');

};

return (

<form  onSubmit={handleSubmit}>

<input

type="text"

value={userId}

onChange={(e) =>  setUserId(e.target.value)}

placeholder="User ID"

/>

<input

type="email"

value={email}

onChange={(e) =>  setEmail(e.target.value)}

placeholder="Email"

/>

<button  type="submit">Login</button>

</form>

);

}

  

export  default  LoginForm;

Angular

// app.module.ts

import { NgModule } from  '@angular/core';

import { BrowserModule } from  '@angular/platform-browser';

import { FormsModule } from  '@angular/forms';

import { AppComponent } from  './app.component';

import { LoginFormComponent } from  './login-form/login-form.component';

  

@NgModule({

declarations: [

AppComponent,

LoginFormComponent

],

imports: [

BrowserModule,

FormsModule

],

providers: [],

bootstrap: [AppComponent]

})

export  class  AppModule { }

  

// app.component.ts

import { Component, OnInit, OnDestroy } from  '@angular/core';

import  Perceptr  from  '@perceptr/web-sdk';

  

@Component({

selector: 'app-root',

template: `

<div class="app">

<h1>Perceptr SDK Demo</h1>

<app-login-form (login)="onLogin($event)"></app-login-form>

</div>

`

})

export  class  AppComponent  implements  OnInit, OnDestroy {

async ngOnInit() {

// Initialize the SDK

Perceptr.init({

projectId: 'your-project-id'

});

await Perceptr.start();

}

ngOnDestroy() {

// Clean up

Perceptr.stop();

}

async onLogin(userData: {userId: string, email: string}) {

awaitPerceptr.identify(userData.userId, {

email: userData.email,

loginTime: new  Date().toISOString()

});

alert('User identified!');

}

}

  

// login-form.component.ts

import { Component, Output, EventEmitter } from  '@angular/core';

  

@Component({

selector: 'app-login-form',

template: `

<form (ngSubmit)="onSubmit()">

<input type="text" [(ngModel)]="userId" name="userId" placeholder="User ID">

<input type="email" [(ngModel)]="email" name="email" placeholder="Email">

<button type="submit">Login</button>

</form>

`

})

export  class  LoginFormComponent {

userId  =  '';

email  =  '';

@Output() login  =  new  EventEmitter<{userId: string, email: string}>();

onSubmit() {

this.login.emit({

userId: this.userId,

email: this.email

});

}

}

Vue

<!-- App.vue -->

<template>

<div id="app">

<h1>Perceptr SDK Demo</h1>

<login-form @login="onLogin" />

</div>

</template>

  

<script>

import Perceptr from '@perceptr/web-sdk';

import LoginForm from './components/LoginForm.vue';

  

export default {

name: 'App',

components: {

LoginForm

},

created() {

// Initialize the SDK

Perceptr.init({

projectId: 'your-project-id'

});

Perceptr.start();

},

beforeUnmount() {

// Clean up

Perceptr.stop();

},

methods: {

async onLogin(userData) {

await Perceptr.identify(userData.userId, {

email: userData.email,

loginTime: new Date().toISOString()

});

alert('User identified!');

}

}

}

</script>

perceptr web-sdk user-session monitoring recording

@rrweb/rrweb-plugin-console-record axios rrweb uuid

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago