Ir al contenido
DevLab

Los resultados en tu backend

Cómo llegan los resultados en cada modo, el SDK y la API juntos, SSE o sondeo, el par que hay que guardar, las consultas puntuales y el webhook firmado del diferido.

En esta página
  1. Cómo llegan los resultados, por modo
  2. SDK y API, en las dos direcciones
  3. SSE o sondeo
  4. Engine no manda webhooks
  5. Guarda el par
  6. Consultas puntuales
  7. El webhook del diferido como contrato
  8. Probar el webhook en local

En el dispositivo (tiempo real): en la página, onResult y stop() → CaptureOutcome; en cualquier momento, GET /results/{userProtocolId}/{protocolMechanicId} o client.retrieveResults(userProtocolId, protocolMechanicId); mientras capturas, el flujo de eventos GET /stream/{userProtocolId}. Diferido (en servidor): el servicio de procesado reproduce la grabación contra Engine y avisa a tu backend con su webhook firmado; después lees GET /results como arriba.

Primero el backend: createEngineAdmin crea a la persona y la inscripción, y la página captura con ese par. Primero el navegador: la página captura con el SDK y tu backend lee después. Las dos se apoyan en lo mismo: tu backend guarda el par al inscribir y, con él, lee GET /results cuando lo necesita (createEngineAdmin().getResults es esa ruta, desde Node). Este módulo guarda el par, lee los resultados y la interpretación guardada, y borra a la persona al acabar; store es tu base de datos. Los bloques de esta página se publican tal cual se ejecutan, así que sus comentarios están en inglés:

JavaScript
// Store and read later, from your backend. At enrolment, keep the pair next to your user: it is all you need to read
// the results later (a report, a dashboard, another session). Engine does not expire results today: they stay until
// you delete the person. `store` is your database; any table with these four columns will do.
import { randomUUID } from 'node:crypto'
import { createEngineAdmin } from '@neurologyca/capture-server'
/**
* @typedef {{ userId: string, externalId: string, userProtocolId: string, protocolMechanicId: string }} Capture
* @typedef {{ insert(c: Capture): Promise<string>, get(captureId: string): Promise<Capture | null>, ofUser(userId: string): Promise<Capture[]>, deleteOfUser(userId: string): Promise<void> }} CaptureStore
* @param {{ store: CaptureStore, engineBase?: string, apiKey?: string, fetch?: typeof fetch }} opts
*/
export function storeAndReadLater({ store, engineBase = process.env.ENGINE_BASE, apiKey = process.env.ENGINE_API_KEY, fetch: fetchImpl }) {
if (!engineBase || !apiKey) throw new Error('Set ENGINE_BASE and ENGINE_API_KEY in your backend environment')
const admin = createEngineAdmin({ baseUrl: engineBase, apiKey, fetch: fetchImpl })
/** @param {Capture} c */
const pairOf = (c) => ({ userProtocolId: c.userProtocolId, protocolMechanicId: c.protocolMechanicId })
return {
// 1 · At enrolment: create the person, enrol them and store the pair. The browser captures with that pair.
/** @param {string} userId your user @param {string} protocolId the protocol in your kit @param {string} [language] of the interpretation */
async enrolPerson(userId, protocolId, language = process.env.NARRATIVE_LANGUAGE ?? 'en') {
const externalId = randomUUID() // opaque: never the email
await admin.createUser({ externalId, name: 'person', narrative: { language } }) // without it, Engine writes in English
const { userProtocolId } = await admin.enrol(externalId, protocolId)
const next = await admin.getNextPosition(userProtocolId)
if (!next) throw new Error('The protocol has no position to capture')
const captureId = await store.insert({ userId, externalId, userProtocolId, protocolMechanicId: next.protocolMechanicId })
return { captureId, userProtocolId, protocolMechanicId: next.protocolMechanicId }
},
// 2 · Whenever you need it: now or weeks later. There is no webhook in real time: if you read right at the end and
// there is no data yet, read again a little later.
/** @param {string} captureId */
async readLater(captureId) {
const c = await store.get(captureId)
if (!c) return null
const { rawResults, aggResults, speech } = await admin.getResults(pairOf(c))
return { rawResults, aggResults, speech }
},
// The stored interpretation, with a protocol that interprets (Measurement does not). Without reAnalyze it is not
// generated or billed again: never ask for it in a loop. With inProgress: true (a 202: Engine is still writing it), it
// is not «no interpretation»: ask again after retryAfterMs (about 30 s when null), a few times at most.
/** @param {string} captureId */
async readInterpretation(captureId) {
const c = await store.get(captureId)
return c ? admin.analyze(pairOf(c)) : null
},
// 3 · When you are done: delete the person and everything of theirs in Engine. It cannot be undone.
/** @param {string} userId */
async forget(userId) {
for (const externalId of new Set((await store.ofUser(userId)).map((c) => c.externalId))) await admin.deleteUser(externalId)
await store.deleteOfUser(userId)
},
}
}

Desde capture-server 0.15.0, getResults devuelve también speech: por step, lo que se preguntó (questionText) y lo que se dijo (transcript) (HCIs y resultados; solo en el Engine del entorno de pruebas). speech es null cuando Engine no manda el bloque. Para leer de una vez todas las mecánicas de una inscripción, getProtocolResults({ userProtocolId }) devuelve { mechanics: [...] }, cada una con su protocolMechanicId, order, rawResults, aggResults y speech; necesita tu key (un token de captura no puede leerla).

La llamada cruda devuelve el mismo cuerpo (recortado a los agregados):

JSON
{
"aggResults": {
"1": {
"mean": {
"valence": 6.751,
"arousal": 69.775,
"Confusion": 14.618,
"Stress_intens": 54.195
}
}
}
}

results.ready como señal, /results como verdad. El evento llega una vez por posición, y no en todos los casos: sigue sondeando GET /results hasta que traiga datos.

JSON
{
"events": ["connected", "hci.warning", "results.ready"]
}

La lista muestra cada nombre de evento una sola vez: hci.warning llega una vez por lote que envías, solo de un indicador que tu contexto incluye, y no es una alerta: DevLab no enseña el nivel que lo dispara (threshold), así que no construyas sobre él. Que se envíe depende del entorno.

Engine no tiene webhooks: usas el flujo de eventos o sondeas. El único webhook del sistema es el del servicio de procesado, hacia tu backend, en el diferido.

Guarda userProtocolId y protocolMechanicId en tu backend al inscribir, no en la pestaña: E_RESULTS_TIMEOUT no es una pérdida, y con el par lees los resultados más tarde. Guarda también tu externalId opaco, nunca el email: es lo que borra a la persona. Hoy Engine no caduca los resultados: siguen ahí hasta que admin.deleteUser(externalId) (DELETE /users/{externalId}) borra a la persona y todo lo suyo, y no se puede deshacer (Supresión y retención). Qué más guardar, y cómo releer gratis la interpretación: Qué guardar.

El catálogo (GET /catalog/protocols, GET /catalog/contexts), el estado de una persona (GET /users/{externalId}/status) y sus inscripciones (GET /users/{externalId}/user-protocols, o admin.listEnrolments) son lecturas simples desde tu backend. Mira la guía de la API HTTP y la referencia de la API.

La interpretación se lee igual: admin.analyze(pair) devuelve la guardada (fromCache: true) si el análisis salió completo; con metadata.status degraded o failed, o sin una guardada, cada llamada la regenera, y eso cuesta tokens del modelo de lenguaje y tiempo: generar una interpretación suele tardar decenas de segundos y puede tardar unos dos minutos de punta a punta (La interpretación): pídela una vez, nunca en bucle. Qué audiencia enviar para que salga de la caché: Qué guardar. Para forzar una nueva, y cuándo no: Pedir una interpretación nueva. Desde capture-server 0.16.0, AnalyzeResult.structured trae entero los datos estructurados de la interpretación; un índice de 0 a 100, si el dominio lo tiene, se lee de ahí con readScoreIndex(result.structured) (Un índice de 0 a 100).

Con el SDK en tiempo real hay una interpretación por sesión desde 0.38.0: la guardada. El texto que vio la persona en la página es el que devuelve después admin.analyze(pair) (fromCache: true), porque stop() espera el aviso de Engine y, si no llega, la lee una vez con POST /analyze en vez de generar otra. SessionReport.interpretationSource (en la página) dice de dónde salió; 'analyze-generated' significa que /analyze tuvo que generarla, y la sesión pudo interpretarse dos veces. Hasta 0.37 había dos interpretaciones de una misma sesión, y las dos se cobraban: ve dos interpretaciones. Por la API HTTP, cada llamada a /analyze/stream sigue generando una nueva que Engine no guarda; con el SDK, solo si pides interpretation: 'stream'.

Cómo salió el análisis lo dice metadata.status; el resto de metadata (modelo, recuento de tokens, ids, tiempos) es interno de Engine. Esta documentación no promete esos campos: no te apoyes en ellos ni los enseñes a tus usuarios, porque pueden cambiar o desaparecer sin aviso.

createWebhookHandler({ secret, nonces, onEvent }) verifica cada entrega. Lo que puedes dar por seguro:

  • Los campos firmados vienen en el cuerpo: ProcessorWebhookEvent.jobId, ProcessorWebhookEvent.captureId, ProcessorWebhookEvent.status (succeeded, failed o, desde capture-server 0.11.0, el no terminal interpreting), ProcessorWebhookEvent.interpretation (en un succeeded), ProcessorWebhookEvent.outcome, ProcessorWebhookEvent.errorCode, ProcessorWebhookEvent.retryable.
  • X-Neuro-Delivery y X-Neuro-Job viajan fuera de la firma: una pista, nunca una autoridad.
  • La firma vale ±300 s alrededor del reloj de tu servidor y cada nonce se guarda 600 s, así que mantén el reloj sincronizado.
  • Las entregas son al menos una vez y sin orden garantizado: actúa solo si el jobId del cuerpo es el que guardaste y el trabajo que guardaste sigue en curso: el estado de tu tabla, o el que devuelve processor.getJob, es uno de queued, downloading, preparing, transcribing, replaying, waiting o interpreting (ProcessorJobStatus). El status del propio evento es succeeded o failed (terminales) o interpreting (un aviso intermedio que no cierra nada). No hagas nada ante un segundo evento, ni ante un interpreting que llega después del terminal.
  • Responde 2xx rápido y haz el trabajo después.
  • Solo HTTPS.
  • Excluye esta ruta de la protección CSRF de tu framework (va firmada, no es un formulario del navegador).

Si una entrega no llega nunca, sondea con processor.getJob(jobId). El manejador recibe un único secret, así que no puede aceptar dos a la vez: rotarlo implica un corte breve, y si no puedes permitirte uno, sondea con processor.getJob mientras lo cambias.

JavaScript
import { createProcessorClient } from '@neurologyca/capture-server'
const processor = createProcessorClient({ url: process.env.PROCESSOR_URL, apiKey: process.env.PROCESSOR_API_KEY })
const job = await processor.getJob(jobId) // el mismo estado que lleva el webhook, cuando lo necesites

Desde capture-server 0.11.0 el trabajo espera la interpretación: succeeded llega cuando está lista o cuando consta que no llegará, y su interpretation dice cuál de las dos. El trabajo es un éxito valga lo que valga: los indicadores están en /results. Qué hacer con cada valor: La interpretación.

Para probar tu manejador sin el servicio, firma tú un evento sintético y enviándolo a tu ruta. capture-server verifica firmas pero no las hace, así que este es el formato que comprueba: la cabecera X-Neuro-Signature: t=<epoch ms>,n=<uuid>,v1=<hex>, donde v1 es el HMAC-SHA256, con tu secreto, de webhook.<t>.<n>.<raw body> (los bytes exactos que envías). Usa un t actual (±300 s) y un n nuevo cada vez.