sa-sdk-javascript: the browser tracking SDK behind the Sensors Data platform

A collection SDK for a specific analytics platform, not a generic tracker

The project is the official web JavaScript tracking SDK from Sensors Data, described as a lightweight collection and tracking SDK for web and H5 pages. It is built with native JavaScript rather than a framework.

The capture modes are the substance of the project. The README lists code tracking, where a developer calls the SDK explicitly, full auto capture, where events are collected without manual instrumentation, the app click map, and visual full capture, where the tracking plan is configured visually rather than in code. The repository description adds web heatmaps and touch maps to that list, and the root of the repository holds a file named heatmap.min.js alongside the other bundles, so the heatmap capability is a distinct piece of shipped code rather than a paragraph in the documentation.

That combination is what makes the SDK specific. A generic analytics library gives you an event API and leaves capture strategy to you. This one carries product decisions about how a session is turned into analysable behaviour, and those decisions are the reason it exists.

The audience is a team that has already chosen Sensors Data as its behaviour analytics platform and needs a browser-side collector that speaks its protocol. The homepage is opensource.sensorsdata.cn, the company behind the SDK is Sensors Data, based in Beijing with teams in Shanghai, Shenzhen, Hefei and Wuhan, and the README points at a separate site for commercial licensing questions.

Four bundle formats sit in the repository root for direct script inclusion

The repository layout is unusual for a JavaScript package and it tells you how the SDK is consumed. Alongside the source tree in core/ and the built output in dist/, the root holds several ready-to-serve files: sensorsdata.min.js, sensorsdata.es6.min.js, sensorsdata.amd.min.js, vapph5define.min.js, heatmap.min.js, sensorsdata.min.d.ts, and version.js.

The naming tells the story. The AMD bundle is for loaders that expect a define call, the es6 bundle is for bundlers that consume ES modules, and the plain minified file is for a script tag. The .d.ts file gives TypeScript projects a type surface, and version.js lets a host page or a wrapper read the build it is running.

The package manifest is minimal and points at the same story. The name is sa-sdk-javascript, the version is 1.28.1, and the main entry is the web build:

{
  "name": "sa-sdk-javascript",
  "version": "1.28.1",
  "main": "dist/web/sensorsdata.js",
}

The vapph5define.min.js file is the odd one out, and it relates to the hybrid app case, where a page runs inside a native container. The test scripts in the same manifest name the corresponding bridge classes, which confirms that path is a supported runtime rather than a leftover artefact.

The test scripts name three runtimes: web, hybrid bridges, and everything together

The scripts in package.json are unusually informative about the internals, because the file names in the test commands describe the environments the SDK is expected to survive.

  "test": "nyc --reporter=text-summary --reporter=text babel-tape-runner unit-test/sensorsdata._.test.js unit-test/sensorsdata.test.js",
  "test:bridge": "nyc --reporter=text-summary --reporter=text babel-tape-runner unit-test/sensorsdata.AndroidBridge.test.js unit-test/sensorsdata.IosBridge.test.js",
  "test:all": "nyc --reporter=text-summary --reporter=text babel-tape-runner unit-test/demo.js unit-test/sensorsdata._.test.js unit-test/sensorsdata.AndroidBridge.test.js unit-test/sensorsdata.IosBridge.test.js unit-test/sensorsdata.test.js",

So the suite is split into a core web test file, a file for the internal underscore-prefixed module, and separate suites for an Android bridge and an iOS bridge. The bridge suites are the interesting part: they mean the SDK is expected to run inside a native WebView and talk to the host application through a bridge, and that this behaviour is covered by tests rather than assumed.

The tooling is babel-tape-runner driving tape style tests, with nyc producing coverage summaries through the text-summary and text reporters. The build script, by contrast, does nothing:

  "build": "echo \"Error: no test specified\" && exit 1",

That is a deliberate signal about the workflow. The dist/ folder and the prebuilt files in the root are the deliverable, and they are produced by a separate internal pipeline rather than by a build anyone can run from this repository. A contributor can run the tests, but cannot regenerate the shipped bundles here.

The CHANGELOG is a compatibility contract, not a convenience

The README carries an explicit warning in Chinese that the SDK may not be fully forward compatible, that you should read the version update notes in CHANGELOG.md, and that if an incompatibility is noted you may need to upgrade the corresponding version of the Sensors Data analysis side.

That sentence describes a two-sided version constraint. The client library is not just a data producer, it is a protocol participant, and the receiving system has to understand what it sends. That is the shape of a first-party SDK tied to its own server product, and it differs from a generic tracker where you own the receiving endpoint and therefore own the compatibility.

For an adoption decision, the practical consequence is that upgrading the SDK is a two-part operation: read the CHANGELOG entry for the version you are moving to, and check whether the platform needs a matching upgrade. The CHANGELOG.md file at the repository root is the place to do that, and the recent release list shows the file is being maintained, with v1.28.1 on 2026-09-10, v1.27.15 on 2026-08-31, and v1.27.14 on 2026-08-14.

The version numbers also tell you how the project ships. They are patch-level increments on a 1.x line, which is the numbering you would expect from a client library that must keep a stable wire contract while adding capture modes.

The licence story has three parts and they do not agree

There are three separate signals about licensing here, and they should be read together rather than separately.

The first is the package manifest. package.json declares the license as Apache-2.0, which is a standard permissive licence.

The second is the licence recorded for the repository itself, which is a custom licence that GitHub cannot classify, with the LICENSE file at the repository root holding the actual terms. The README links to that file under a License heading rather than naming a licence.

The third is the commercial path. The README says that for more commercial authorisation information about the Sensors Data tracking SDK you should visit the dedicated site, and it lists contact channels for commercial cooperation and product integration. The project is described as an open source commercial user behaviour collection SDK, which is the vendor's own framing of a piece of software that is open in the sense that the code is readable while the commercial use of the platform is licensed separately.

The mismatch between Apache-2.0 in the manifest and an unclassifiable custom LICENSE file is the part to settle before you ship. If your build pipeline reads the licence field from the manifest for compliance checks, it will report the wrong thing. Read the LICENSE file, and if you intend to use the SDK in a commercial product, get the authorisation question answered through the vendor contact route the README lists.

Where the SDK is the wrong tool

Three situations rule this project out.

The first is a team that wants vendor-neutral collection. If your data strategy is to send events to your own API, or to a platform you host, this SDK sends data into the Sensors Data product instead, and you cannot redirect it without reimplementing the capture logic it provides. Building your own collector, a queue in local storage, a beacon send, and a small event API is a weekend of work for the code tracking mode alone, and it keeps the data path under your control.

The second is a server-side rendering or strict privacy regime. The product description calls the SDK lightweight, but the capture modes it offers, especially visual full capture and the heatmap, are built around collecting everything a user does on the page. If your consent requirements or your data minimisation policy forbid that, the auto capture modes are the wrong tool even if the code tracking mode would be acceptable, because the feature set is what the platform is built to do.

The third is the build story. The manifest build script exits with an error, the shipped bundles in the repository root cannot be regenerated from this repository, and the unit-test directory referenced by the test commands is not among the top-level entries you can see. You can consume the published files, and you can run the tests if you obtain the missing pieces, but the repository is not a self-sufficient build.

Editorial conclusion

Adopt sa-sdk-javascript if your product is already inside the Sensors Data ecosystem and you need its specific capture modes, including the heatmap, the click map, and the hybrid app bridge, without rebuilding an analytics pipeline of your own. Do not adopt it as a neutral open source tracking library, because the licence recorded in the repository is a custom agreement rather than a standard one, and because the platform it reports into is a commercial product with its own commercial authorisation path. Verify three things before you commit: what the LICENSE file actually grants you, whether the bundled file you plan to load from the repository root matches the version you have pinned, and whether the CHANGELOG for your target version requires a matching upgrade on the Sensors Data server side.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. sensorsdata/sa-sdk-javascript on GitHub