Ir al contenido
DevLab

En Engine 1.5, una página abría una sesión, capturaba un rato y pedía la interpretación. En Engine 2, una persona se inscribe en un protocolo, y cada captura es una posición de él, con un plan de steps (ver Protocolos). Crear usuarios e inscribirlos es trabajo de tu backend.

  • La API key nunca llega al navegador: tu backend obtiene los tokens con la key y hace de proxy de Engine.
  • Capture sigue enviando geometría facial, nunca imágenes.
Tema Engine 1.5 Engine 2
Token POST /token con user, tenant y securityKey: un token por usuario final POST /token con apiKey: un token por key. El usuario final pasa del token a cada petición (externalId, ids de inscripción)
Usuarios Se creaban al vuelo con el primer token Los crea tu backend con POST /users; externalId es único por organización
Qué capturas Una sesión libre (POST /session, con su order) Una posición de un protocolo en el que el usuario está inscrito (POST /user-protocols), identificada por userProtocolId y protocolMechanicId, con su plan de steps
Taxonomía de la interpretación Campos del cuerpo de POST /session POST /user-protocols/{userProtocolId}/{protocolMechanicId}/context
Narrativa (voz, profundidad, idioma) En el cuerpo de la sesión En el perfil del usuario (POST /users y PATCH /users/{external_id}), más audience en /analyze
Envío de frames POST /process-kpn-emo con sessionId, step = order y baseline La misma ruta con userProtocolId, protocolMechanicId y el step del plan; sin el flag baseline; featuresMeta en cada frame
Baseline Una sesión con baseline: true; la validez la calculaba el cliente Su propia ruta, POST y GET /users/{app_user}/baseline; el servidor dice si es válido
Resultados GET /results/{sessionId} GET /results/{userProtocolId}/{protocolMechanicId} (también por step y por inscripción)
Interpretación POST /analyze con sessionId, timeStart, timeEnd POST /analyze con userProtocolId, protocolMechanicId, step y audience opcionales, con caché por audiencia; también POST /analyze/stream
Eventos GET /stream/{sessionId} GET /stream/{userProtocolId}, por inscripción, que se cierra con stream.end y un reason
Listar sesiones GET /sessions/ GET /user-protocols/{userProtocolId}/{protocolMechanicId}/sessions y GET /users/{external_id}/status
Constellation Lite lite_analysis en la sesión No forma parte del API público de Engine 2; pregunta a Neurologyca

Esta guía cubre la integración, no tus datos: para usuarios y baselines existentes, pregunta a Neurologyca.

SDK de Engine 1.5 SDK de Engine 2
createNeuroClient createProtocolClient
defineNeuroCapture Sin componente: createProtocolClient y tus propias pantallas (Steps y marcado)
siteKeyTokenProvider y la pasarela alojada Retirados: el proxy de tu backend añade el token (Tu backend)
narrative Rechazada con un mensaje: la narrativa va en el perfil del usuario (POST y PATCH /users/{external_id}), desde tu backend
lite_analysis Rechazada: no forma parte de Engine 2; pregunta a Neurologyca
contextText Sin equivalente: el único texto libre que recibe la interpretación es la transcripción (la frase query sigue existiendo)
interpretationTimeoutMs Renombrada analyzeTimeoutMs
triggerAnalysis en el cliente Por captura (captureProtocol)
— Un paquete de servidor nuevo, @neurologyca/capture-server, para crear usuarios, inscribirlos y generar el kit de un contexto

Tu proxy pasa de las rutas de Engine 1.5 a las 13 rutas que llama el SDK de Engine 2.

El catálogo, el estado y el bloqueo de usuarios, el borrado con confirmación, Measurement, las microintervenciones y los scopes de las keys. Empieza por el quickstart.

Si ya tienes la versión previa anterior del SDK de Engine 2 (0.25), estos son los cambios que debes hacer, según el changelog de @neurologyca/capture (0.26.0 Breaking y 0.27.0) y el de @neurologyca/capture-server 0.9.0. La lista completa está en el Changelog del SDK.

  1. <neuro-capture> desaparece: usa createProtocolClient o createRecordingClient, describeStep y tus propias pantallas. Lo que el elemento hacía por ti (mantener la pantalla encendida, el aviso beforeunload) ahora es tuyo: usa keepScreenOn y guardUnload.
  2. stop() resuelve con el resultado: un CaptureOutcome en vivo, un RecordingResult al grabar.
  3. RecordingSessionHandle ya no extiende ProtocolSessionHandle: usa createRecordingClient, que no necesita cast.
  4. Una sola forma para E_CONFLICT: e.reason y e.conflict.<campo>.
  5. El cliente de grabación (@neurologyca/capture/record) graba solo MP4/H.264.
  6. Una grabación rechaza un captureId que ya está guardado en el navegador (E_CAPTURE_ID_IN_USE).
  7. RecordingResult tiene un storage obligatorio y ProtocolSessionHandle tiene captureId y stepTiming(): un doble de test escrito a mano debe añadirlos.
  8. CaptureSource gana { type: 'frames' }, así que un switch exhaustivo sobre source.type deja de compilar.
  9. La base de datos de grabaciones pasa a la versión 2: cierra las pestañas con un SDK anterior antes de grabar.
  10. capture.global.js no registra ninguna etiqueta: la API está en window.NeuroCapture.
  11. @neurologyca/capture-server 0.9.0 exige Node 20.3 o posterior (engines.node es >=20.3).
  1. El navegador no necesita token: crea el cliente sin getToken (ahora es opcional), detrás del proxy de tu backend (createEngineProxy).
  2. Sube las grabaciones con uploadRecording, la mitad del navegador del contrato cuya mitad de servidor es createUploadReceiver.
  3. stepDurations avisa por defecto y tiene un 'off'.
  4. Desde la 0.27.0, un <video> es una fuente completa: su audio llega a la transcripción (con su src puesto antes), su final es el final de la fuente (source.ended) y puedes grabarlo.

Si tienes 0.27, estos son los cambios que debes hacer hasta @neurologyca/capture 0.43.0 y @neurologyca/capture-server 0.19.0, según sus changelogs (los Breaking de 0.36.0, 0.36.3, 0.38.0, 0.42.0, 0.42.1 y 0.43.0, y el tipo más ancho de 0.28.0). La lista completa está en el Changelog del SDK.

  1. 0.28.0: ManifestStep.endedBy gana 'source', el step que cerró el fin de la fuente grabada (un <video> o un stream que terminó); antes decía 'timer'. Un switch exhaustivo sobre él necesita el caso nuevo.
  2. 0.36.0 (kodec 5): FORWARDED_CODEC_EVENTS ya no lista hubert-enabled, hubert-revoked, voice-enabled ni voice-revoked; un listener sobre ellos no salta nunca.
  3. 0.36.0 renombró PlanStep.targetConstellationHciId a targetHciId y 0.36.3 lo deshizo (con ProtocolSummary.group en @neurologyca/capture-server 0.14.3): desde 0.27 el nombre no cambia, pero el código escrito contra 0.36.0 a 0.36.2 vuelve a targetConstellationHciId.
  4. 0.38.0: stop() ya no genera una segunda interpretación: espera la que guarda Engine (hasta analyzeTimeoutMs) y solo entonces llama una vez a POST /analyze, así que puede tardar más; analyze.progress solo llega con interpretation: 'stream' (El resultado).
  5. 0.38.0: PlanStep gana los obligatorios expectsSpeech y presentationSeconds, y SessionReport gana interpretationSource, interpretationMode y streamDropsDuringWait: el código que los construye a mano debe añadirlos.
  6. 0.42.0: un transcribe.selfHost.wasmPaths de texto es ahora un prefijo que debe acabar en /, bajo el que tu servidor sirve el par de onnxruntime que pide el dispositivo (CSP y transcripción).
  7. 0.42.0: createProtocolClient lanza E_UNKNOWN_OPTION con una opción que no conoce, como ya hacía createRecordingClient: quita de la configuración cualquier clave de más.
  8. 0.42.0: ProtocolClientHandle gana prepare, release y cacheStatus (y RecordingClientHandle, prepare y release), SessionReport gana startup y transcriptionLoad, y CaptureStartError gana stage y reason: un doble de test tipado debe añadirlos.
  9. 0.42.1 y 0.43.0: StartupMessageKey gana 'first-frame.timeout-media' y 'first-frame.face-reload-failed': un Record<StartupMessageKey, string> con tus propios textos debe añadir las dos.
  10. 0.43.0: StartupReport.schema es 1 | 2 y PreparedBlock.prepareId puede ser null. Un receptor de informes de arranque valida el esquema 2 con @neurologyca/capture-server 0.19.0 o posterior (Los informes de arranque).
  11. 0.43.0 (kodec 5.0.0-rc.14): una fuente que ya terminó cuando empieza la captura falla en el acto, con CaptureStartError y stage: 'source'; pasa un stream vivo o un vídeo que aún se reproduce.
  1. client.prepare() y client.release() (0.42.0) cargan los modelos antes de Empezar (Preparar antes de Empezar), y keepPrepared (0.43.0) los guarda de una captura a la siguiente (Guardar los modelos entre capturas).
  2. startup, onStartupStage y STARTUP_MESSAGES (0.42.0) enseñan el arranque etapa a etapa, con topes para que no se cuelgue (La pantalla de arranque).
  3. signal en captureProtocol (0.42.0) cancela una captura mientras arranca, y captureProtocol({ transcribe: false }) hace una captura sin micrófono en un cliente configurado con transcripción.

Si tienes 0.43, estos son los cambios que debes hacer hasta @neurologyca/capture 0.45.0 y @neurologyca/capture-server 0.20.1, según sus changelogs (0.44.0, 0.45.0, 0.20.0 y 0.20.1). Ninguno rompe en ejecución: cambia la lectura de un 202 y algunos tipos ganan campos obligatorios. PlanStep.expectsSpeech (0.38.0) y targetConstellationHciId (0.36.3) no cambian en este tramo. Si vienes de una versión anterior, sigue antes De 0.27 a 0.43, cuya 0.43.0 es la última versión incompatible. La lista completa está en el Changelog del SDK.

  1. 0.44.0: client.analyze() (en createProtocolClient y createRecordingClient) resuelve a AnalyzeAnswer, que añade los obligatorios inProgress y retryAfterMs a interpretation, fromCache y raw: un doble de test tipado que construya su resultado debe añadir los dos (inProgress: false, retryAfterMs: null para una respuesta normal).
  2. 0.44.0: al cerrar una captura, un 202 ANALYSIS_IN_PROGRESS ya no acaba en E_INTERPRETATION_TIMEOUT: el SDK espera y vuelve a pedirla (analysis.in-progress) y, si se agota la espera, acaba con el nuevo E_ANALYSIS_IN_PROGRESS (recuperable, estado timeout). El código que ramifica por E_INTERPRETATION_TIMEOUT para decir «interpretación pendiente» debe tratar también E_ANALYSIS_IN_PROGRESS (Errores), y un switch exhaustivo sobre ProtocolErrorCode necesita el caso nuevo.
  3. 0.44.0 y 0.20.0: una interpretación null con inProgress: true es «interpretando», no «sin interpretación»: mira inProgress antes de dar por definitivo un interpretation: null y vuelve a pedirla pasados retryAfterMs (El 202 de la interpretación).
  4. 0.20.0: AnalyzeResult (analyze() y EngineAdmin.analyze) y AudienceReading (analyzeForAudiences) ganan los obligatorios inProgress y retryAfterMs, ProtocolSummary y su group ganan interpreted (boolean | null), y TenantKit gana kind ('context' | 'measurement'): un doble de test tipado de cualquiera de ellos debe añadirlos.
  5. 0.20.0: buildTenantKit ya no lanza E_KIT_NO_CONTEXT con Measurement: da kind: 'measurement', con taxonomy.contextId: MEASUREMENT_CONTEXT_ID y un aviso de capturar con triggerAnalysis: false. Ramifica por kit.kind donde capturabas E_KIT_NO_CONTEXT para caer en una configuración fija de Measurement (Tu backend).
  1. credentials (0.45.0) en createProtocolClient, createRecordingClient y urlTokenProvider: 'include' para un proxy en otro origen que decide por tu cookie de sesión, con cors: { origins, credentials: true } en createEngineProxy y capture-server 0.20.1, que expone Retry-After a esa página (Un proxy en otro origen).
  2. 0.45.0: un /analyze repetido tras un 202 recibe solo lo que queda de la espera, así que el cierre acaba como mucho unos 10 s después de analyzeTimeoutMs.