Installation

One package covers both tiers. In on-device mode the Web SDK runs the full measurement in the browser — face tracking, pulse recovery, and metric estimation all happen locally, and raw camera frames never leave the page. In cloud mode only face tracking runs in the browser: the cropped face is sent to our servers, which compute the metrics. See Cloud overview for the comparison and Cloud privacy for what the cloud mode transmits.

Install

npm install @neccessory/web-sdk

import { createMeasurement } from '@neccessory/web-sdk';

TypeScript declarations ship with the package; there is no separate @types install.

If you would rather not use a bundler, load the UMD build with one script tag and use the neccessory global:

<script src="https://neccessory.com/neccessory-sdk/neccessory-sdk.js"></script>
<script>
  const m = neccessory.createMeasurement({ videoEl });
</script>

Requirements

• A secure context — HTTPS or localhost. Browsers refuse camera access otherwise.
• A modern browser with WebAssembly and Web Worker support (see Browser support).

Where the engine and models come from

The SDK itself is small. The measurement engine, its workers, and the model files are served from https://neccessory.com and loaded cross-origin at runtime — you do not host them, and there is nothing to copy into your build.

Two consequences worth planning for:

• Authorize the model download. There are two ways. The recommended one is a model grant: your backend calls POST /sdk/v1/models/grant with your key (HMAC-signed, so the secret stays server-side), gets a short-lived token, and passes it to the page. Any origin works — the grant is bound to your key, not to a domain. The alternative is to send us every origin you will run on, staging and preview hosts included, and we register them on our side; an unregistered origin then fails at startup rather than mid-measurement.

  This only gates the model download. Signed calls to /sdk/v1/* answer any origin — see Where you may call from.

  // 1. On your server, once per page load (the grant is valid for 15 minutes):
  //    POST /sdk/v1/models/grant  →  { "grant": "…", "expiresAt": 1785… }
  
  // 2. In the browser:
  createMeasurement({ videoEl, modelGrant: grantFromYourBackend });

• Nothing else needs configuring. The default is correct. Pass assetOrigin only if we gave you a dedicated host:

  createMeasurement({ videoEl, assetOrigin: 'https://cdn.example.com' });

Next: Quickstart.