Registry / observability / smartlook-client

smartlook-client

JSON →
library10.0.0jsnpmunverified

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.

npm install smartlook-client
INSTALL
IMPORT
SIG · SMARTLOOK-CLIENT
S
smartlook-client
observabilityjavascriptv10.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Smartlook
import Smartlook from 'smartlook-client'
const Smartlook = require('smartlook-client')
Since v9.0.0, the package includes an ESM build, making `import` the preferred syntax for modern JavaScript projects. CommonJS `require` is still supported for Node.js environments or projects not using ESM.
Interceptors
import type { Interceptors } from 'smartlook-client'
Import types separately using `import type` for enhanced type-checking and potential bundle optimization in TypeScript projects.
Smartlook.init
Smartlook.init(key, params)
SmartlookClient.init(key, params)
The primary API is accessed directly from the default export `Smartlook`. There is no separate `SmartlookClient` export or similar.

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' });
Debug
Known issues
breakingVersion 7.0.0 introduced significant breaking changes by adding support for a new Record API and completely removing the old Consent API. Integrations relying on the previous Consent API must be updated.
fix
Migrate your implementation to use the new Record API. Refer to the Smartlook documentation on 'Web/Consent Sensitive Data' for details.
affects: >=7.0.0
breakingVersion 8.0.0 removed support for the legacy web SDK. This version also added official support for the Relay proxy.
fix
Ensure your project is not relying on the legacy web SDK. If using a Relay proxy, refer to Smartlook documentation on 'Relay proxy' for configuration guidance.
affects: >=8.0.0
breakingVersion 9.0.0 added full ESM build support. While CommonJS `require` might still function, modern applications should transition to `import` syntax for optimal compatibility and future-proofing.
fix
Update your import statements from `const Smartlook = require('smartlook-client')` to `import Smartlook from 'smartlook-client'` in ESM-aware environments.
affects: >=9.0.0
breakingIn version 10.0.0, the `relayProxyUrl` parameter now strictly respects the protocol specified in the URL. If your relay proxy URL previously omitted a protocol or used an incorrect one, it might now fail.
fix
Ensure your `relayProxyUrl` configuration includes the full and correct protocol (e.g., `'https://my-proxy-domain.com/'`).
affects: >=10.0.0
gotchaSetting `cookies: false` in the `init` parameters disables storing recording metadata in cookies, relying only on local storage. This will block the ability to connect visitors between different domains and subdomains.
fix
Only set `cookies: false` if cross-domain visitor tracking is not required, or if you have alternative methods for visitor identification across domains. The default value is `true`.
affects: >=7.0.2
gotchaThe `region` parameter determines where data will be captured and stored. It should only be changed if explicitly instructed by your Smartlook sales manager to ensure data residency compliance.
fix
Do not modify the `region` parameter unless you have confirmed the correct region for your project with Smartlook support.
affects: >=6.0.0
Errors
Common errors & fixes
Uncaught TypeError: Smartlook.init is not a function
Attempting to call `init` before the Smartlook client is fully loaded or imported, or using an incorrect import method in a mixed CommonJS/ESM project.
fix
Ensure `import Smartlook from 'smartlook-client'` is at the top of your module, or verify that the script loading order correctly places Smartlook initialization after the library is available. For CJS environments with ESM interop, `const Smartlook = require('smartlook-client').default;` might be necessary, though `import` is preferred for new code.
Smartlook: Missing or invalid project key provided to init().
`Smartlook.init()` was called without a valid project key string as its first argument.
fix
Provide your project's Smartlook key: `Smartlook.init('YOUR_SMARTLOOK_PROJECT_KEY', { ...params })`.
Smartlook recording not visible for content loaded within an iframe.
By default, Smartlook attempts to connect with a parent window when loaded in an iframe, which can lead to delays or missed recordings if the parent doesn't also record the same project or if communication fails.
fix
When loading your application in an iframe, initialize Smartlook with the `standalone: true` option to prevent connection attempts with the parent: `Smartlook.init(key, { standalone: true })`.
Upgrade
Version history
10.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
14 hits · last 30 days
node
10
OpenAI (training)
2
Resources
smartlook-client — npm install smartlook-client · libregistry