Migrar desde Engine 1.5
Qué cambia al pasar una integración de Engine 1.5 a Engine 2, ruta por ruta.
Qué cambia en el modelo
Sección titulada «Qué cambia en el modelo»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.
Qué se mantiene
Sección titulada «Qué se mantiene»- 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.
Ruta por ruta
Sección titulada «Ruta por ruta»| 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.
Si usas el SDK
Sección titulada «Si usas el SDK»| 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.
Qué añade Engine 2
Sección titulada «Qué añade 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.
De 0.25 a 0.27
Sección titulada «De 0.25 a 0.27»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.
<neuro-capture>desaparece: usacreateProtocolClientocreateRecordingClient,describeStepy tus propias pantallas. Lo que el elemento hacía por ti (mantener la pantalla encendida, el avisobeforeunload) ahora es tuyo: usakeepScreenOnyguardUnload.stop()resuelve con el resultado: unCaptureOutcomeen vivo, unRecordingResultal grabar.RecordingSessionHandleya no extiendeProtocolSessionHandle: usacreateRecordingClient, que no necesita cast.- Una sola forma para
E_CONFLICT:e.reasonye.conflict.<campo>. - El cliente de grabación (
@neurologyca/capture/record) graba solo MP4/H.264. - Una grabación rechaza un
captureIdque ya está guardado en el navegador (E_CAPTURE_ID_IN_USE). RecordingResulttiene unstorageobligatorio yProtocolSessionHandletienecaptureIdystepTiming(): un doble de test escrito a mano debe añadirlos.CaptureSourcegana{ type: 'frames' }, así que unswitchexhaustivo sobresource.typedeja de compilar.- La base de datos de grabaciones pasa a la versión 2: cierra las pestañas con un SDK anterior antes de grabar.
capture.global.jsno registra ninguna etiqueta: la API está enwindow.NeuroCapture.@neurologyca/capture-server0.9.0 exige Node 20.3 o posterior (engines.nodees>=20.3).
Nuevo o recomendado
Sección titulada «Nuevo o recomendado»- El navegador no necesita token: crea el cliente sin
getToken(ahora es opcional), detrás del proxy de tu backend (createEngineProxy). - Sube las grabaciones con
uploadRecording, la mitad del navegador del contrato cuya mitad de servidor escreateUploadReceiver. stepDurationsavisa por defecto y tiene un'off'.- Desde la 0.27.0, un
<video>es una fuente completa: su audio llega a la transcripción (con susrcpuesto antes), su final es el final de la fuente (source.ended) y puedes grabarlo.
De 0.27 a 0.43
Sección titulada «De 0.27 a 0.43»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.
- 0.28.0:
ManifestStep.endedBygana'source', el step que cerró el fin de la fuente grabada (un<video>o un stream que terminó); antes decía'timer'. Unswitchexhaustivo sobre él necesita el caso nuevo. - 0.36.0 (kodec 5):
FORWARDED_CODEC_EVENTSya no listahubert-enabled,hubert-revoked,voice-enablednivoice-revoked; un listener sobre ellos no salta nunca. - 0.36.0 renombró
PlanStep.targetConstellationHciIdatargetHciIdy 0.36.3 lo deshizo (conProtocolSummary.groupen@neurologyca/capture-server0.14.3): desde 0.27 el nombre no cambia, pero el código escrito contra 0.36.0 a 0.36.2 vuelve atargetConstellationHciId. - 0.38.0:
stop()ya no genera una segunda interpretación: espera la que guarda Engine (hastaanalyzeTimeoutMs) y solo entonces llama una vez aPOST /analyze, así que puede tardar más;analyze.progresssolo llega coninterpretation: 'stream'(El resultado). - 0.38.0:
PlanStepgana los obligatoriosexpectsSpeechypresentationSeconds, ySessionReportganainterpretationSource,interpretationModeystreamDropsDuringWait: el código que los construye a mano debe añadirlos. - 0.42.0: un
transcribe.selfHost.wasmPathsde 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). - 0.42.0:
createProtocolClientlanzaE_UNKNOWN_OPTIONcon una opción que no conoce, como ya hacíacreateRecordingClient: quita de la configuración cualquier clave de más. - 0.42.0:
ProtocolClientHandleganaprepare,releaseycacheStatus(yRecordingClientHandle,prepareyrelease),SessionReportganastartupytranscriptionLoad, yCaptureStartErrorganastageyreason: un doble de test tipado debe añadirlos. - 0.42.1 y 0.43.0:
StartupMessageKeygana'first-frame.timeout-media'y'first-frame.face-reload-failed': unRecord<StartupMessageKey, string>con tus propios textos debe añadir las dos. - 0.43.0:
StartupReport.schemaes1 | 2yPreparedBlock.prepareIdpuede sernull. Un receptor de informes de arranque valida el esquema 2 con@neurologyca/capture-server0.19.0 o posterior (Los informes de arranque). - 0.43.0 (kodec
5.0.0-rc.14): una fuente que ya terminó cuando empieza la captura falla en el acto, conCaptureStartErrorystage: 'source'; pasa un stream vivo o un vídeo que aún se reproduce.
Nuevo o recomendado
Sección titulada «Nuevo o recomendado»client.prepare()yclient.release()(0.42.0) cargan los modelos antes de Empezar (Preparar antes de Empezar), ykeepPrepared(0.43.0) los guarda de una captura a la siguiente (Guardar los modelos entre capturas).startup,onStartupStageySTARTUP_MESSAGES(0.42.0) enseñan el arranque etapa a etapa, con topes para que no se cuelgue (La pantalla de arranque).signalencaptureProtocol(0.42.0) cancela una captura mientras arranca, ycaptureProtocol({ transcribe: false })hace una captura sin micrófono en un cliente configurado con transcripción.
De 0.43 a 0.45
Sección titulada «De 0.43 a 0.45»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.
Cambios que hacer
Sección titulada «Cambios que hacer»- 0.44.0:
client.analyze()(encreateProtocolClientycreateRecordingClient) resuelve aAnalyzeAnswer, que añade los obligatoriosinProgressyretryAfterMsainterpretation,fromCacheyraw: un doble de test tipado que construya su resultado debe añadir los dos (inProgress: false, retryAfterMs: nullpara una respuesta normal). - 0.44.0: al cerrar una captura, un
202 ANALYSIS_IN_PROGRESSya no acaba enE_INTERPRETATION_TIMEOUT: el SDK espera y vuelve a pedirla (analysis.in-progress) y, si se agota la espera, acaba con el nuevoE_ANALYSIS_IN_PROGRESS(recuperable, estadotimeout). El código que ramifica porE_INTERPRETATION_TIMEOUTpara decir «interpretación pendiente» debe tratar tambiénE_ANALYSIS_IN_PROGRESS(Errores), y unswitchexhaustivo sobreProtocolErrorCodenecesita el caso nuevo. - 0.44.0 y 0.20.0: una interpretación
nullconinProgress: truees «interpretando», no «sin interpretación»: mirainProgressantes de dar por definitivo uninterpretation: nully vuelve a pedirla pasadosretryAfterMs(El 202 de la interpretación). - 0.20.0:
AnalyzeResult(analyze()yEngineAdmin.analyze) yAudienceReading(analyzeForAudiences) ganan los obligatoriosinProgressyretryAfterMs,ProtocolSummaryy sugroupgananinterpreted(boolean | null), yTenantKitganakind('context' | 'measurement'): un doble de test tipado de cualquiera de ellos debe añadirlos. - 0.20.0:
buildTenantKitya no lanzaE_KIT_NO_CONTEXTcon Measurement: dakind: 'measurement', contaxonomy.contextId: MEASUREMENT_CONTEXT_IDy un aviso de capturar contriggerAnalysis: false. Ramifica porkit.kinddonde capturabasE_KIT_NO_CONTEXTpara caer en una configuración fija de Measurement (Tu backend).
Nuevo o recomendado
Sección titulada «Nuevo o recomendado»credentials(0.45.0) encreateProtocolClient,createRecordingClientyurlTokenProvider:'include'para un proxy en otro origen que decide por tu cookie de sesión, concors: { origins, credentials: true }encreateEngineProxyycapture-server0.20.1, que exponeRetry-Aftera esa página (Un proxy en otro origen).- 0.45.0: un
/analyzerepetido tras un202recibe solo lo que queda de la espera, así que el cierre acaba como mucho unos 10 s después deanalyzeTimeoutMs.