Skip to content
DevLab

In Engine 1.5 a page opened a session, captured for a while and asked for the interpretation. In Engine 2 a person is enrolled in a protocol, and each capture is one position of it, with a plan of steps (see Protocols). Creating users and enrolling them is your backend’s job.

  • The API key never reaches the browser: your backend mints tokens and proxies Engine.
  • Capture still sends facial geometry, never images.
Topic Engine 1.5 Engine 2
Token POST /token with user, tenant and securityKey: one token per end user POST /token with apiKey: one token per key. The end user moves from the token to each request (externalId, enrolment ids)
Users Created on the fly with the first token Created by your backend with POST /users; externalId is unique per organization
What you capture A free session (POST /session, with its order) A position of a protocol the user is enrolled in (POST /user-protocols), identified by userProtocolId and protocolMechanicId, with its plan of steps
Taxonomy of the interpretation Fields in the body of POST /session POST /user-protocols/{userProtocolId}/{protocolMechanicId}/context
Narrative (voice, depth, language) In the body of the session In the user’s profile (POST /users and PATCH /users/{external_id}), plus audience in /analyze
Sending frames POST /process-kpn-emo with sessionId, step = order and baseline The same route with userProtocolId, protocolMechanicId and the step of the plan; no baseline flag; featuresMeta on every frame
Baseline A baseline: true session; validity worked out by the client Its own route, POST and GET /users/{app_user}/baseline; the server says whether it is valid
Results GET /results/{sessionId} GET /results/{userProtocolId}/{protocolMechanicId} (also per step and per enrolment)
Interpretation POST /analyze with sessionId, timeStart, timeEnd POST /analyze with userProtocolId, protocolMechanicId, optional step and audience, cached per audience; also POST /analyze/stream
Events GET /stream/{sessionId} GET /stream/{userProtocolId}, per enrolment, closed with stream.end and a reason
Listing sessions GET /sessions/ GET /user-protocols/{userProtocolId}/{protocolMechanicId}/sessions and GET /users/{external_id}/status
Constellation Lite lite_analysis in the session Not part of the public Engine 2 API; ask Neurologyca

This guide covers the integration, not your data: for existing users and baselines, ask Neurologyca.

Engine 1.5 SDK Engine 2 SDK
createNeuroClient createProtocolClient
defineNeuroCapture No component: createProtocolClient and your own screens (Steps and marking)
siteKeyTokenProvider and the hosted gateway Removed: your backend’s proxy adds the token (Your backend)
narrative Rejected with a message: the narrative goes in the user’s profile (POST and PATCH /users/{external_id}), from your backend
lite_analysis Rejected: not part of Engine 2; ask Neurologyca
contextText No equivalent: the only free text the interpretation receives is the transcript (the query phrase still exists)
interpretationTimeoutMs Renamed analyzeTimeoutMs
triggerAnalysis on the client Per capture (captureProtocol)
— A new server package, @neurologyca/capture-server, for creating users, enrolling them and building the kit of a context

Your proxy grows from the routes of Engine 1.5 to the 13 routes the Engine 2 SDK calls.

The catalogue, user status and blocking, deletion with confirmation, Measurement, microinterventions, and key scopes. Start with the quickstart.

If you already run the previous preview of the Engine 2 SDK (0.25), these are the changes to make, from the changelog of @neurologyca/capture (0.26.0 Breaking and 0.27.0) and of @neurologyca/capture-server 0.9.0. The full list is in SDK changelog.

  1. <neuro-capture> is removed: use createProtocolClient or createRecordingClient, describeStep and your own screens. What the element did for you (keeping the screen on, the beforeunload guard) is now yours: use keepScreenOn and guardUnload.
  2. stop() resolves with the outcome: a CaptureOutcome live, a RecordingResult when recording.
  3. RecordingSessionHandle no longer extends ProtocolSessionHandle: use createRecordingClient, which needs no cast.
  4. One shape for E_CONFLICT: e.reason and e.conflict.<field>.
  5. The recording client (@neurologyca/capture/record) records MP4/H.264 only.
  6. A recording refuses a captureId already stored in the browser (E_CAPTURE_ID_IN_USE).
  7. RecordingResult has a required storage, and ProtocolSessionHandle has captureId and stepTiming(): a hand-written test double must add them.
  8. CaptureSource gains { type: 'frames' }, so an exhaustive switch on source.type stops compiling.
  9. The recordings database moves to version 2: close tabs with an older SDK before recording.
  10. capture.global.js registers no tag: the API is on window.NeuroCapture.
  11. @neurologyca/capture-server 0.9.0 requires Node 20.3 or later (engines.node is >=20.3).
  1. The browser needs no token: create the client without getToken (it is now optional), behind your backend’s proxy (createEngineProxy).
  2. Upload recordings with uploadRecording, the browser half of the contract whose server half is createUploadReceiver.
  3. stepDurations warns by default and has an 'off'.
  4. From 0.27.0, a <video> is a full source: its audio reaches transcription (with its src set before), its end is the end of the source (source.ended), and you can record it.

If you run 0.27, these are the changes to make up to @neurologyca/capture 0.43.0 and @neurologyca/capture-server 0.19.0, from their changelogs (the Breaking of 0.36.0, 0.36.3, 0.38.0, 0.42.0, 0.42.1 and 0.43.0, and the wider type of 0.28.0). The full list is in SDK changelog.

  1. 0.28.0: ManifestStep.endedBy gains 'source', the step that the end of the recorded source closed (a <video> or a stream that finished); before, it said 'timer'. An exhaustive switch over it needs the new case.
  2. 0.36.0 (kodec 5): FORWARDED_CODEC_EVENTS no longer lists hubert-enabled, hubert-revoked, voice-enabled and voice-revoked; a listener on them never fires.
  3. 0.36.0 renamed PlanStep.targetConstellationHciId to targetHciId and 0.36.3 undid it (with ProtocolSummary.group in @neurologyca/capture-server 0.14.3): coming from 0.27 the name does not change, but code written against 0.36.0 to 0.36.2 goes back to targetConstellationHciId.
  4. 0.38.0: stop() no longer generates a second interpretation: it waits for the one Engine stores (up to analyzeTimeoutMs) and only then calls POST /analyze once, so it can take longer; analyze.progress only arrives with interpretation: 'stream' (The outcome).
  5. 0.38.0: PlanStep gains the required expectsSpeech and presentationSeconds, and SessionReport gains interpretationSource, interpretationMode and streamDropsDuringWait: code that builds them by hand must add them.
  6. 0.42.0: a transcribe.selfHost.wasmPaths string is now a prefix that must end in /, under which your host serves the onnxruntime pair the device asks for (CSP and transcription).
  7. 0.42.0: createProtocolClient throws E_UNKNOWN_OPTION for an option it does not know, as createRecordingClient already did: remove any extra key from the config.
  8. 0.42.0: ProtocolClientHandle gains prepare, release and cacheStatus (and RecordingClientHandle, prepare and release), SessionReport gains startup and transcriptionLoad, and CaptureStartError gains stage and reason: a typed test double must add them.
  9. 0.42.1 and 0.43.0: StartupMessageKey gains 'first-frame.timeout-media' and 'first-frame.face-reload-failed': a Record<StartupMessageKey, string> of your own texts must add both.
  10. 0.43.0: StartupReport.schema is 1 | 2 and PreparedBlock.prepareId can be null. A receiver of startup reports validates schema 2 with @neurologyca/capture-server 0.19.0 or later (Startup reports).
  11. 0.43.0 (kodec 5.0.0-rc.14): a source that has already ended when the capture starts fails at once, with CaptureStartError and stage: 'source'; pass a live stream or a video that is still playing.
  1. client.prepare() and client.release() (0.42.0) load the models before Start (Prepare before Start), and keepPrepared (0.43.0) keeps them from one capture to the next (Keep the models between captures).
  2. startup, onStartupStage and STARTUP_MESSAGES (0.42.0) show the startup stage by stage, with caps so it cannot hang (The startup screen).
  3. signal in captureProtocol (0.42.0) cancels a capture while it starts, and captureProtocol({ transcribe: false }) runs one capture without the microphone on a client configured with transcription.

If you run 0.43, these are the changes to make up to @neurologyca/capture 0.45.0 and @neurologyca/capture-server 0.20.1, from their changelogs (0.44.0, 0.45.0, 0.20.0 and 0.20.1). None of them breaks at runtime: what changes is the reading of a 202 and some types that gain required fields. PlanStep.expectsSpeech (0.38.0) and targetConstellationHciId (0.36.3) do not change in this stretch. Coming from an earlier version, first follow From 0.27 to 0.43, whose 0.43.0 is the last breaking release. The full list is in SDK changelog.

  1. 0.44.0: client.analyze() (on createProtocolClient and createRecordingClient) resolves to AnalyzeAnswer, which adds the required inProgress and retryAfterMs to interpretation, fromCache and raw: a typed test double that builds its result must add both (inProgress: false, retryAfterMs: null for an ordinary answer).
  2. 0.44.0: at the close of a capture, a 202 ANALYSIS_IN_PROGRESS no longer ends with E_INTERPRETATION_TIMEOUT: the SDK waits and asks again (analysis.in-progress) and, if the wait runs out, ends with the new E_ANALYSIS_IN_PROGRESS (recoverable, status timeout). Code that branches on E_INTERPRETATION_TIMEOUT to say “interpretation pending” must also handle E_ANALYSIS_IN_PROGRESS (Errors), and an exhaustive switch over ProtocolErrorCode needs the new case.
  3. 0.44.0 and 0.20.0: a null interpretation with inProgress: true means “interpreting”, not “none”: check inProgress before treating interpretation: null as final, and ask again after retryAfterMs (The 202 of the interpretation).
  4. 0.20.0: AnalyzeResult (analyze() and EngineAdmin.analyze) and AudienceReading (analyzeForAudiences) gain the required inProgress and retryAfterMs, ProtocolSummary and its group gain interpreted (boolean | null), and TenantKit gains kind ('context' | 'measurement'): a typed test double of any of them must add them.
  5. 0.20.0: buildTenantKit no longer throws E_KIT_NO_CONTEXT for Measurement: it gives kind: 'measurement', with taxonomy.contextId: MEASUREMENT_CONTEXT_ID and a notice to capture with triggerAnalysis: false. Branch on kit.kind where you caught E_KIT_NO_CONTEXT to fall back to a fixed Measurement configuration (Your backend).
  1. credentials (0.45.0) on createProtocolClient, createRecordingClient and urlTokenProvider: 'include' for a proxy on another origin that decides by your session cookie, with cors: { origins, credentials: true } in createEngineProxy and capture-server 0.20.1, which exposes Retry-After to that page (A proxy on another origin).
  2. 0.45.0: an /analyze asked again after a 202 gets only what is left of the wait, so the close ends at most about 10 s past analyzeTimeoutMs.