Cloud Quickstart

your backend ──NCS1──> POST /sdk/v1/cloud/sessions
                       ← data = { sessionId, sessionToken, wsUrl, frameSpec, … }
        │
        └── the whole `data` ──> your page ──WSS──> face crops ──> live events ──> result

// request
{
  "platform": "web",               // "web" | "ios" | "android"
  "durationSec": 60,               // 20 .. 180, default 60
  "features": ["hrv", "bp", "spo2"], // a subset; core metrics are always on
  "consent": true,                 // REQUIRED — see below
  "clientRef": "user-42"           // optional, ≤ 64 chars, your own correlation id
}

// 201
{
  "ok": true,
  "data": {
    "sessionId": "cj_…",
    "sessionToken": "<payload>.<signature>",
    "wsUrl": "wss://infer.neccessory.com/v1/stream",
    "expiresAt": 1785000000000,
    "maxDurationSec": 60,          // echoes the durationSec you asked for
    "features": ["hrv", "bp", "spo2"], // the sets this session will compute and bill
    "frameSpec": {
      "kind": "face-crop",
      "width": 36, "height": 36, "channels": 3,
      "layout": "nhwc", "dtype": "uint8", "colorSpace": "srgb",
      "padRatio": 0,
      "nominalRateHz": 30, "maxRateHz": 32,
      "compression": "none"
    }
  }
}

import crypto from 'node:crypto';

const sha256 = (v) => crypto.createHash('sha256').update(v).digest('hex');

function signHeaders(keyId, secret, method, path, body = '') {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce = crypto.randomBytes(12).toString('base64url');
  const canonical = ['NCS1', method.toUpperCase(), path, timestamp, nonce, sha256(body)].join('\n');
  return {
    'x-key-id': keyId,
    'x-timestamp': timestamp,
    'x-nonce': nonce,
    'x-signature': crypto.createHmac('sha256', sha256(secret)).update(canonical).digest('base64'),
    'content-type': 'application/json',
  };
}

const path = '/sdk/v1/cloud/sessions';
const body = JSON.stringify({
  platform: 'web',
  durationSec: 60,
  features: ['hrv', 'bp', 'spo2'],
  consent: true,
});

const res = await fetch(`https://neccessory.com${path}`, {
  method: 'POST',
  headers: signHeaders(process.env.NC_KEY_ID, process.env.NC_SECRET, 'POST', path, body),
  body,
});
const { data } = await res.json();
// Return the whole `data` object to the page. It is all public: the token, the
// socket address, the session id and the frame spec. Your secret is not in it.
return Response.json(data);

<video id="cam" autoplay playsinline muted width="480"></video>
<p>Heart rate: <span id="hr">--</span> bpm</p>
<p id="status"></p>
<button id="start">Start</button>

<script type="module">
  import { createMeasurement } from '@neccessory/web-sdk';

  // The whole `data` object from POST /sdk/v1/cloud/sessions, forwarded verbatim
  // by your backend: { sessionId, sessionToken, wsUrl, maxDurationSec, frameSpec }.
  const session = await fetch('/your-backend/nc-session', { method: 'POST' })
    .then((r) => r.json());

  const m = createMeasurement({
    videoEl: document.getElementById('cam'),
    mode: 'cloud',
    session,
    delivery: 'auto',
  });

  m.onRealtime((update) => {
    if (update.heartRate != null) {
      document.getElementById('hr').textContent = update.heartRate;
    }
  });

  m.onStage((stage) => {
    // 'requestingCamera' | 'loadingModels' | 'connecting' | 'ready'
    // and, when streaming falls back to batch, 'uploading' then 'processing'.
    document.getElementById('status').textContent = stage;
  });

  m.onResult((result) => {
    // result.origin === 'cloud', result.attested === true
    console.log(result);
  });

  m.onError((err) => console.error(err.code, err.message));

  document.getElementById('start').addEventListener('click', () => m.start());
</script>

{
  "origin": "cloud",
  "attested": true,
  "quality": { "level": "good", "score": 0.82, "usable": true }
  // … all the usual sections
}