SensorsData JavaScript SDK

Common errors

• ReferenceError: sensorsdata is not defined

  cause The SDK script was not loaded or initialized correctly, or the global `sensorsdata` object is not available in the current execution scope.
  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.

• TypeError: sensorsdata.init is not a function

  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.
  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.

• Tracking data not appearing in SensorsData backend

  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.
  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).

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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`.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install sa-sdk-javascript npm
• yarn add sa-sdk-javascript yarn
• pnpm add sa-sdk-javascript pnpm

Imports

• sensorsdata
  wrong:

  const sensorsdata = require('sa-sdk-javascript');

  correct:

  import sensorsdata from 'sa-sdk-javascript';

  For modern module environments (ESM), use a default import. CommonJS `require` is still supported for older Node.js environments or build systems.
• sensorsdata.init
  wrong:

  import { init } from 'sa-sdk-javascript';
  init({ /* config */ });

  correct:

  import sensorsdata from 'sa-sdk-javascript';
  sensorsdata.init({ /* config */ });

  The `init` method is a property of the main `sensorsdata` instance, not a separate named export. All core functionalities are accessed via this instance.
• sensorsdata (global)

  <script src="path/to/sa-sdk-javascript.min.js"></script>
  <script>sensorsdata.init({ /* config */ });</script>

  When included directly via a script tag in HTML, the SDK typically exposes a global `sensorsdata` object on `window` for immediate use.

Quickstart

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.

import sensorsdata from 'sa-sdk-javascript';

// Initialize the SDK with your SensorsData project configuration
sensorsdata.init({
  // Replace with your SensorsData data collection server URL
  serverUrl: process.env.SENSORS_DATA_SERVER_URL ?? 'https://your-sensorsdata-server.com/sa?project=your_project',
  // Enable debug mode to see logs in the console (useful during development)
  show_log: true,
  // Automatically track page views when the URL changes
  autoTrack: {
    pageview: true
  },
  // Enable heatmap functionality (requires server-side configuration)
  heatmap: {
    clickmap: 'default',
    scroll_nickname: 'default'
  },
  // Use IndexedDB for local data persistence before sending
  use_indexeddb: true,
  // Configure specific plugin options, e.g., for user attributes
  preset_properties: {
    // Example: Capture the user's browser language on first visit
    '$browser_language': navigator.language
  }
});

// Track a custom event, e.g., 'UserSignup'
sensorsdata.track('UserSignup', {
  signup_method: 'Email',
  signup_time: new Date().toISOString()
});

// Set or update user profile properties
sensorsdata.setProfile({
  email: 'user@example.com',
  account_type: 'Premium'
});

// Log in a user (associates anonymous data with a known user ID)
sensorsdata.login('unique_user_id_123');

// Once logged in, track another event for the identified user
sensorsdata.track('ProductPurchased', {
  product_id: 'SKU789',
  price: 99.99,
  currency: 'USD'
});

console.log('SensorsData SDK initialized and events tracked.');