Registry / data / sa-sdk-javascript

sa-sdk-javascript

library1.27.11jsnpmunverified

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.

data

npm install sa-sdk-javascript

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SA-SDK-JAVASCRIPT

sa-sdk-javascript

datajavascriptv1.27.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

sensorsdata

✓ import sensorsdata from 'sa-sdk-javascript';

✗ const sensorsdata = require('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

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

✗ import { init } from 'sa-sdk-javascript'; 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.

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

Debug

Known issues

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

affects: >=1.27.1

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

affects: All versions

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

affects: >=1.27.2

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

affects: >=1.27.8

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

affects: <1.27.8

Errors

Common errors & fixes

ReferenceError: sensorsdata is not defined

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

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

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

Upgrade

Version history

1.27.11latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

3 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sensorsdata/sa-sdk-javascript ↗

packagehttps://www.npmjs.com/package/sa-sdk-javascript ↗

homepagehttps://www.sensorsdata.cn ↗