{"id":11973,"library":"sa-sdk-javascript","title":"SensorsData JavaScript SDK","description":"The `sa-sdk-javascript` is the official client-side SDK for SensorsData, a leading user behavior analytics platform. It facilitates comprehensive data collection from web applications, supporting various tracking methods including code-based, full-stack, and visual full-stack event tracking. The current stable version is 1.27.11, with frequent patch releases addressing bug fixes, performance improvements, and feature additions, as evidenced by its rapid iteration cadence. Key differentiators include its status as an open-source commercial SDK, robust support for diverse data collection strategies, and proven stability across a large customer base. The SDK is designed to help businesses implement data-driven strategies by providing reliable user behavior insights.","status":"active","version":"1.27.11","language":"javascript","source_language":"en","source_url":"https://github.com/sensorsdata/sa-sdk-javascript","tags":["javascript","sensorsdata","sdk"],"install":[{"cmd":"npm install sa-sdk-javascript","lang":"bash","label":"npm"},{"cmd":"yarn add sa-sdk-javascript","lang":"bash","label":"yarn"},{"cmd":"pnpm add sa-sdk-javascript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For modern module environments (ESM), use a default import. CommonJS `require` is still supported for older Node.js environments or build systems.","wrong":"const sensorsdata = require('sa-sdk-javascript');","symbol":"sensorsdata","correct":"import sensorsdata from 'sa-sdk-javascript';"},{"note":"The `init` method is a property of the main `sensorsdata` instance, not a separate named export. All core functionalities are accessed via this instance.","wrong":"import { init } from 'sa-sdk-javascript';\ninit({ /* config */ });","symbol":"sensorsdata.init","correct":"import sensorsdata from 'sa-sdk-javascript';\nsensorsdata.init({ /* config */ });"},{"note":"When included directly via a script tag in HTML, the SDK typically exposes a global `sensorsdata` object on `window` for immediate use.","symbol":"sensorsdata (global)","correct":"<script src=\"path/to/sa-sdk-javascript.min.js\"></script>\n<script>sensorsdata.init({ /* config */ });</script>"}],"quickstart":{"code":"import sensorsdata from 'sa-sdk-javascript';\n\n// Initialize the SDK with your SensorsData project configuration\nsensorsdata.init({\n  // Replace with your SensorsData data collection server URL\n  serverUrl: process.env.SENSORS_DATA_SERVER_URL ?? 'https://your-sensorsdata-server.com/sa?project=your_project',\n  // Enable debug mode to see logs in the console (useful during development)\n  show_log: true,\n  // Automatically track page views when the URL changes\n  autoTrack: {\n    pageview: true\n  },\n  // Enable heatmap functionality (requires server-side configuration)\n  heatmap: {\n    clickmap: 'default',\n    scroll_nickname: 'default'\n  },\n  // Use IndexedDB for local data persistence before sending\n  use_indexeddb: true,\n  // Configure specific plugin options, e.g., for user attributes\n  preset_properties: {\n    // Example: Capture the user's browser language on first visit\n    '$browser_language': navigator.language\n  }\n});\n\n// Track a custom event, e.g., 'UserSignup'\nsensorsdata.track('UserSignup', {\n  signup_method: 'Email',\n  signup_time: new Date().toISOString()\n});\n\n// Set or update user profile properties\nsensorsdata.setProfile({\n  email: 'user@example.com',\n  account_type: 'Premium'\n});\n\n// Log in a user (associates anonymous data with a known user ID)\nsensorsdata.login('unique_user_id_123');\n\n// Once logged in, track another event for the identified user\nsensorsdata.track('ProductPurchased', {\n  product_id: 'SKU789',\n  price: 99.99,\n  currency: 'USD'\n});\n\nconsole.log('SensorsData SDK initialized and events tracked.');","lang":"javascript","description":"This quickstart demonstrates how to initialize the SensorsData SDK, track a custom event, set user profile properties, and log in a user, showcasing fundamental data collection patterns."},"warnings":[{"fix":"Review the `CHANGELOG.md` for `v1.27.1` and subsequent versions carefully. Identify any removed plugins or APIs that your application relies on and update your code or configuration accordingly. Some integrations may require re-evaluation.","message":"Version 1.27.1 introduced a 'v2' packaging version which removed several automatically built-in plugins and deprecated some APIs. This can lead to breaking changes for existing integrations relying on these removed functionalities.","severity":"breaking","affected_versions":">=1.27.1"},{"fix":"Before upgrading the SDK, always check the `CHANGELOG.md` and the official documentation for both the SDK and your SensorsData backend. Ensure your backend meets the minimum version requirements for new SDK features or changes to avoid data ingestion issues.","message":"The SDK may not be fully backward compatible across major version upgrades of the SensorsData analytics platform itself. Upgrading the client SDK often requires verifying compatibility with your backend SensorsData instance.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of this shift in priority when setting global properties. If you previously relied on `registerPage` properties having higher precedence, you may need to adjust your property registration logic or explicitly override with `track` call properties if `properties_priority` is set to 3 or higher.","message":"The `properties_priority: 3` configuration, introduced in `v1.27.2`, changes the priority of properties. Properties registered via `register` will now take precedence over those registered with `registerPage`.","severity":"gotcha","affected_versions":">=1.27.2"},{"fix":"If tracking data is not being received reliably, check for ad-blocker interference. For `v1.27.8` and above, consider configuring `custom_server_url` in the SDK initialization options. Note that this functionality typically requires a customized SensorsData backend instance to process data from the alternative URL.","message":"Ad-blockers can interfere with data collection by blocking requests to the default `sa.gif` endpoint. Version 1.27.8 introduced the `custom_server_url` parameter to specify an alternative data collection endpoint, but this requires a custom backend configuration.","severity":"gotcha","affected_versions":">=1.27.8"},{"fix":"For versions prior to 1.27.8, ensure that any parameters or keywords for visualization tools are placed correctly in the URL, typically before the hash fragment. Version 1.27.8 includes a fix addressing this specific issue, improving compatibility with hash-mode URLs.","message":"Prior to `v1.27.8`, if a webpage's URL used a hash-based routing (`example.com/#/path`) and visualization keywords were incorrectly appended *after* the hash, it could prevent the visualization definition mode from functioning correctly.","severity":"gotcha","affected_versions":"<1.27.8"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"If using a script tag, ensure it's loaded before any `sensorsdata` calls. If using modules, verify the `import sensorsdata from 'sa-sdk-javascript';` statement is present and executed correctly before usage.","cause":"The SDK script was not loaded or initialized correctly, or the global `sensorsdata` object is not available in the current execution scope.","error":"ReferenceError: sensorsdata is not defined"},{"fix":"Confirm that you are importing the default export `sensorsdata` directly (e.g., `import sensorsdata from 'sa-sdk-javascript';`). Ensure no other variables are shadowing the `sensorsdata` identifier and that the SDK's main instance is correctly loaded.","cause":"The `sensorsdata` object being accessed does not have an `init` method. This often indicates an incorrect import or an issue with the SDK's initialization.","error":"TypeError: sensorsdata.init is not a function"},{"fix":"Verify the `serverUrl` and `project` in your SDK initialization are correct. Check the browser's network tab for failed requests to your `serverUrl`. Enable `show_log: true` in your SDK configuration for detailed client-side debugging logs. Consider implementing `custom_server_url` if ad-blockers are suspected (requires backend support).","cause":"Common causes include an incorrect `serverUrl` in the SDK configuration, ad-blocker interference, network connectivity issues, or misconfigured project settings on the SensorsData platform.","error":"Tracking data not appearing in SensorsData backend"}],"ecosystem":"npm"}