Smartlook Client for Frontend Integration

10.0.0 · active · verified Tue Apr 21

The `smartlook-client` is the official JavaScript client library designed for integrating Smartlook's user session recording and analytics into web applications. Currently at stable version 10.0.0, this package is under active development with frequent major and minor releases, typically introducing new features or improvements every few months. Key differentiators include robust support for advanced network recording, enabling the capture of request/response bodies and headers, and a flexible interceptor system to precisely control and obscure sensitive data across various capture points like URLs, network calls, errors, focus events, and clicks. It provides granular control over data capture regions, cookie usage, and integrates seamlessly with Smartlook's Relay Proxy for self-hosted data routing. The client also supports modern web features such as 1st party iframes and shadow DOM, ensuring comprehensive recording coverage across complex web interfaces.

Common errors

Warnings

Install

Imports

Quickstart

This quickstart initializes the Smartlook client with a project key, demonstrates configuration for region, cookie behavior, advanced network recording, and sets up interceptors to control and obscure data from clicks, network requests, and errors. It also includes examples of identifying visitors and tracking custom events.

import Smartlook from 'smartlook-client';

// For a real application, retrieve your Smartlook key from environment variables
const SMARTLOOK_KEY = process.env.SMARTLOOK_KEY ?? 'YOUR_SMARTLOOK_PROJECT_KEY';

if (SMARTLOOK_KEY === 'YOUR_SMARTLOOK_PROJECT_KEY') {
  console.warn("Please replace 'YOUR_SMARTLOOK_PROJECT_KEY' with your actual Smartlook project key for proper functionality.");
}

Smartlook.init(SMARTLOOK_KEY, {
  region: 'eu', // Specify your data residency region ('eu' or 'us')
  cookies: true, // true by default; set to false to disable cookie storage for metadata
  advancedNetwork: {
    websockets: true, // Enable recording of WebSocket traffic
    allowedUrls: [/^https?:\/\/api\.example\.com\/.*/], // Regex patterns for URLs to record bodies/headers
    allowedHeaders: ['x-custom-request-id'] // Non-standard headers to record
  },
  interceptors: {
    click: (data, context) => {
      // Prevent recording clicks on elements marked with data-no-smartlook-click
      if (context.target instanceof HTMLElement && context.target.dataset.noSmartlookClick) {
        return false;
      }
      // Modify click data, e.g., obscure text content
      return { ...data, text: 'CLICK_OBSCURED' };
    },
    network: (request, response) => {
      // Obscure sensitive response bodies from specific endpoints
      if (response && response.url.includes('/sensitive-data')) {
        return { ...response, body: '[OBSCURED_SENSITIVE_DATA]' };
      }
      return response;
    },
    error: (data, context) => {
      // Filter out known or non-critical errors
      if (data.message?.includes('Expected informational error')) {
        return; // Do not record this error
      }
      // Annotate recorded errors
      return { ...data, message: `[Smartlook Intercepted] ${data.message}` };
    }
  },
  relayProxyUrl: 'https://my-proxy-domain.com/' // Optional: URL for self-hosted relay proxy
});

console.log('Smartlook client initialized and configured.');

// Example: Identifying a visitor with custom properties
Smartlook.identify('user-unique-id-789', {
  name: 'Jane Doe',
  email: 'jane.doe@example.com',
  plan: 'premium'
});

// Example: Tracking a custom event
Smartlook.track('SignUpCompleted', { method: 'email', campaign: 'spring2024' });

view raw JSON →