@perceptr/web-sdk
Version:
Perceptr Web SDK for recording and monitoring user sessions
714 lines (326 loc) • 9.01 kB
Markdown
MIT © [Perceptr](https://github.com/bebofit/perceptr-web-sdk)
[](https://www.npmjs.com/package/@perceptr/web-sdk)
[](https://opensource.org/licenses/MIT)
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.
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.
```bash
npm install @perceptr/web-sdk
yarn add @perceptr/web-sdk
pnpm add @perceptr/web-sdk
```
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>` |
```javascript
import Perceptr, { CoreConfig, UserIdentity } from "@perceptr/web-sdk";
```
Initializes the SDK with the provided configuration.
```javascript
Perceptr.init({
projectId: 'your-project-id',
debug: true
});
```
Starts recording the user session.
```javascript
await Perceptr.start();
```
Stops the recording and returns the session data.
```javascript
await Perceptr.stop();
```
Temporarily pauses the recording.
```javascript
Perceptr.pause();
```
Resumes a paused recording.
```javascript
Perceptr.resume();
```
Associates the current session with a user identity.
```javascript
await Perceptr.identify('user-123', {
email: 'user@example.com',
name: 'John Doe',
plan: 'premium'
});
```
```typescript
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
}
```
```typescript
interface UserIdentity {
distinctId: string; // Required: Unique identifier for the user
email?: string; // Optional: User's email
name?: string; // Optional: User's name
[]: any; // Optional: Any additional user properties
}
```
```html
<!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>
```
```jsx
// 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;
```
```typescript
// 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>
```