{"id":16220,"library":"smartlook-client","title":"Smartlook Client for Frontend Integration","description":"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.","status":"active","version":"10.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/smartlook/smartlook-client","tags":["javascript","smartlook","smartlook-client","typescript"],"install":[{"cmd":"npm install smartlook-client","lang":"bash","label":"npm"},{"cmd":"yarn add smartlook-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add smartlook-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Smartlook = require('smartlook-client')","symbol":"Smartlook","correct":"import Smartlook from 'smartlook-client'"},{"note":"Import types separately using `import type` for enhanced type-checking and potential bundle optimization in TypeScript projects.","symbol":"Interceptors","correct":"import type { Interceptors } from 'smartlook-client'"},{"note":"The primary API is accessed directly from the default export `Smartlook`. There is no separate `SmartlookClient` export or similar.","wrong":"SmartlookClient.init(key, params)","symbol":"Smartlook.init","correct":"Smartlook.init(key, params)"}],"quickstart":{"code":"import Smartlook from 'smartlook-client';\n\n// For a real application, retrieve your Smartlook key from environment variables\nconst SMARTLOOK_KEY = process.env.SMARTLOOK_KEY ?? 'YOUR_SMARTLOOK_PROJECT_KEY';\n\nif (SMARTLOOK_KEY === 'YOUR_SMARTLOOK_PROJECT_KEY') {\n  console.warn(\"Please replace 'YOUR_SMARTLOOK_PROJECT_KEY' with your actual Smartlook project key for proper functionality.\");\n}\n\nSmartlook.init(SMARTLOOK_KEY, {\n  region: 'eu', // Specify your data residency region ('eu' or 'us')\n  cookies: true, // true by default; set to false to disable cookie storage for metadata\n  advancedNetwork: {\n    websockets: true, // Enable recording of WebSocket traffic\n    allowedUrls: [/^https?:\\/\\/api\\.example\\.com\\/.*/], // Regex patterns for URLs to record bodies/headers\n    allowedHeaders: ['x-custom-request-id'] // Non-standard headers to record\n  },\n  interceptors: {\n    click: (data, context) => {\n      // Prevent recording clicks on elements marked with data-no-smartlook-click\n      if (context.target instanceof HTMLElement && context.target.dataset.noSmartlookClick) {\n        return false;\n      }\n      // Modify click data, e.g., obscure text content\n      return { ...data, text: 'CLICK_OBSCURED' };\n    },\n    network: (request, response) => {\n      // Obscure sensitive response bodies from specific endpoints\n      if (response && response.url.includes('/sensitive-data')) {\n        return { ...response, body: '[OBSCURED_SENSITIVE_DATA]' };\n      }\n      return response;\n    },\n    error: (data, context) => {\n      // Filter out known or non-critical errors\n      if (data.message?.includes('Expected informational error')) {\n        return; // Do not record this error\n      }\n      // Annotate recorded errors\n      return { ...data, message: `[Smartlook Intercepted] ${data.message}` };\n    }\n  },\n  relayProxyUrl: 'https://my-proxy-domain.com/' // Optional: URL for self-hosted relay proxy\n});\n\nconsole.log('Smartlook client initialized and configured.');\n\n// Example: Identifying a visitor with custom properties\nSmartlook.identify('user-unique-id-789', {\n  name: 'Jane Doe',\n  email: 'jane.doe@example.com',\n  plan: 'premium'\n});\n\n// Example: Tracking a custom event\nSmartlook.track('SignUpCompleted', { method: 'email', campaign: 'spring2024' });","lang":"typescript","description":"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."},"warnings":[{"fix":"Migrate your implementation to use the new Record API. Refer to the Smartlook documentation on 'Web/Consent Sensitive Data' for details.","message":"Version 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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"Version 8.0.0 removed support for the legacy web SDK. This version also added official support for the Relay proxy.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Update your import statements from `const Smartlook = require('smartlook-client')` to `import Smartlook from 'smartlook-client'` in ESM-aware environments.","message":"Version 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.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Ensure your `relayProxyUrl` configuration includes the full and correct protocol (e.g., `'https://my-proxy-domain.com/'`).","message":"In 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.","severity":"breaking","affected_versions":">=10.0.0"},{"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`.","message":"Setting `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.","severity":"gotcha","affected_versions":">=7.0.2"},{"fix":"Do not modify the `region` parameter unless you have confirmed the correct region for your project with Smartlook support.","message":"The `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.","severity":"gotcha","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Uncaught TypeError: Smartlook.init is not a function"},{"fix":"Provide your project's Smartlook key: `Smartlook.init('YOUR_SMARTLOOK_PROJECT_KEY', { ...params })`.","cause":"`Smartlook.init()` was called without a valid project key string as its first argument.","error":"Smartlook: Missing or invalid project key provided to init()."},{"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 })`.","cause":"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.","error":"Smartlook recording not visible for content loaded within an iframe."}],"ecosystem":"npm"}