Ir al contenido
DevLab

Probar tu integración

Prueba con datos deterministas: tu sandbox, un vídeo tuyo, frames sintéticos para CI, el SDK con una cámara falsa, estados forzados y el webhook.

En esta página
  1. Tu sandbox
  2. El playground en DevLab
  3. Preguntas, idioma y transcripción
  4. Audiencia
  5. Ir y volver, y tus sesiones de las últimas 24 h
  6. Duración en el playground
  7. El SDK con un vídeo tuyo
  8. Frames sintéticos para tu CI
  9. El SDK en CI, con una cámara falsa
  10. Forzar estados
  11. El webhook, en local

Tu entorno de pruebas es tu sandbox (Tus entornos). Crea personas con un externalId opaco (el createUser del SDK genera un UUID) y bórralas al terminar con DELETE /users/{externalId} (Engine exige { "confirm": "<externalId>" } en el cuerpo; ver Privacidad). Nunca pruebes con personas reales salvo con su consentimiento.

Playground, en la cabecera, ejecuta capturas reales contra tu organización y enseña cada llamada. Tiene seis secciones: Medir, Flujo, Baseline, Resultados, Diferido (en servidor) y SDK y API (el mapa completo, con lo que tiene cada una y lo que ves cuando falta algo, está en Dónde está cada cosa). En el playground, una sesión es lo que mides cada vez que pulsas Medir (la sesión de Engine de esa posición, con sus steps); una ejecución es la persona de prueba que DevLab crea y su panel de llamadas, que puede juntar varias sesiones.

  • Sin iniciar sesión, o sin un equipo con key activa, no se mide ni se guarda nada: ves el ejemplo grabado. La barra dice «Sin iniciar sesión: nada se mide ni se guarda» o «Sin equipo: nada se mide ni se guarda»; un equipo cuya key se revocó tiene su propio mensaje, «Tu equipo no tiene una key activa». Entra, o pide un equipo con key activa (Tu cuenta de DevLab).
  • Contexto y protocolo. En Medir y en Diferido eliges qué medir en dos pasos: primero Contexto (Measurement arriba, cada contexto con su número de protocolos) y después Protocolo, que lista solo los protocolos de ese contexto; un contexto con un solo protocolo lo enseña fijo. Al cambiar de contexto se elige su primer protocolo. La elección se guarda solo en esta pestaña del navegador, es la misma en las dos secciones y nunca va en la URL. En Diferido, un contexto que este entorno no graba sale desactivado, con el motivo, y con un protocolo cuyo kit no tiene un contexto asignado Grabar sale desactivado, con el motivo. Con un solo contexto no hay mando Contexto.
  • Origen. En Medir y en Baseline eliges de dónde vienen los frames: Vídeo de muestra (por defecto, cuando este DevLab los tiene), Cámara o Muestra sintética. Si este DevLab no tiene vídeos de muestra, el playground lo dice y pasa a la cámara si tu navegador tiene una, o si no a la muestra sintética. La muestra sintética son frames, no vídeo, así que solo funciona por la API HTTP y no se puede grabar en Diferido.
  • Preparar la captura. Con sesión y equipo activo, Medir prepara la captura al entrar (descarga el modelo de la cara, y el reconocimiento de voz por sí solo únicamente con buena conexión, sin ahorro de datos y con pantalla de al menos 1024 px; estar en la caché no basta) y enseña el progreso, etapa a etapa, antes de pulsar Medir: la barra dice «Listo · pulsa Medir» al acabar. El reconocimiento de voz es grande (unos 160 MB), así que cuando no se descarga solo, la página dice que lo hará al pulsar Medir y ofrece Descargar ahora y Cancelar descarga; si el reconocimiento de voz deja de avanzar, Seguir sin voz sigue sin él en esa captura. Baseline usa la misma cara preparada (la voz la deja para la sesión); solo con una grabación diferida en curso carga la suya. Qué se descarga y desde dónde está en Privacidad.
  • Misma persona, mismo origen. Un baseline y las mediciones que lo usan deben salir de la misma persona y del mismo origen. Si cambias el origen de una persona ya capturada, un diálogo («Misma persona, mismo origen») te pide crear una persona nueva o mantener el origen.
  • Límites. En producción, cada equipo puede tener 10 ejecuciones de prueba vivas a la vez y cada cuenta puede crear 30 al día (por día natural en UTC). Pasado cualquiera de los dos límites, DevLab responde playground.limit con un Retry-After. El límite del equipo (10 vivas) se libera borrando: borra alguna tuya (Borrar ahora), o pide al admin de tu organización que borre otras de tu equipo. El límite diario (30) cuenta todas las ejecuciones creadas hoy, también las borradas, así que borrar no ayuda: espera a lo que diga el Retry-After (la próxima medianoche UTC). Las personas de prueba se borran en Engine a las 24 horas. Los entornos de pruebas pueden permitir más ejecuciones que producción. Una ejecución reúne hasta 5 sesiones (playground.enrol_limit); después, Persona → Nueva.
  • Diferido. Grabar necesita sesión, un equipo con key activa, tu organización con el procesado en diferido activado (Procesado en diferido) y un servicio de procesado que responda, con un protocolo cuyo kit tenga un contexto (Measurement siempre lo tiene). El diferido está activado en una organización nueva salvo que Neurologyca lo desactivara al crearla; Neurologyca lo activa o desactiva. En un DevLab con grabación, con el diferido de tu organización desactivado, Diferido dice «Tu organización no tiene activado el diferido», explica qué es y enseña el ejemplo grabado, sin botón de grabar. Si no, ves Preview y el ejemplo grabado, sin botón de grabar: «El servicio de procesado no responde ahora mismo» significa que pruebes más tarde; si la página no muestra ningún botón de grabar, este DevLab no ofrece grabación (una subida responde entonces uploads.unavailable).
  • Resultados y descargas. Resultados muestra los recuentos, un gráfico pequeño por indicador y una tabla de la sesión que enseña (por defecto, la última; ver Ir y volver, y tus sesiones de las últimas 24 h), con descargas que se hacen en tu navegador; en Medir se llega por Explora los N indicadores (HCIs) y su serie o por Ver los indicadores de la barra. Resultados no enseña el texto de la interpretación. Con varios steps, eliges el rango: Toda la sesión (la de entrada), una pregunta o un step; las fichas, la serie, la tabla y las descargas lo siguen. Cada media dice quién la da: la de Engine con un step, el valor de sesión de Engine para los indicadores relevantes en toda la sesión y, si no, la media de los frames, calculada por DevLab. Con una pregunta o un step, enseña también la pregunta y Lo que dijo. La interpretación está en la tarjeta de resultado de Medir y de Diferido: empieza por su resumen y, debajo, en una línea, para quién se escribió la lectura y la emoción principal (el término del catálogo de Engine, en inglés). El chip de la tarjeta de Medir dice en qué punto está: Interpretando… mientras llega, Interpretado, Sin interpretación o, con Measurement, Solo indicadores. Si Engine tarda más de lo que el SDK la espera (E_INTERPRETATION_TIMEOUT, también por la API HTTP cuando POST /analyze sigue respondiendo 202), el chip dice Engine sigue interpretando y la tarjeta ofrece Volver a pedir la interpretación: pide POST /analyze una vez; si está lista, se pinta, y si Engine sigue con ella, la barra de estado lo dice y puedes volver a pedirla en un minuto. Cuando trae un índice de 0 a 100 (por ejemplo wellness_index), la tarjeta lo enseña tras esa línea, con su frase tal como llega; cuando no lo trae, lo dice Datos técnicos de la respuesta. Las llamadas de una ejecución se pueden descargar como JSON o como script de cURL. Junto a cada valor, Resultados y las tarjetas de Medir y Diferido enseñan la clave de Engine de la que sale, con el interruptor Claves de la respuesta (encendido por defecto); apágalo para ocultarlas. En el entorno estable de DevLab, Lo que dijo no aparece mientras speech solo exista en el Engine de pruebas.
  • El código. SDK y API enseña el código de cada pieza (primero el SDK), y Descargar el starter en vivo te da el flujo completo de Medir en un zip, sin tu key (Tu kit): incluye la vista de cámara, la lectura posterior desde tu backend y la carga de los modelos; el gráfico, las fichas de resultados y la comprobación del dispositivo se copian desde Código.

Con un protocolo que tiene preguntas o steps de voz, la barra de mandos de Medir y de Diferido añade hasta tres mandos. Cada elección es por protocolo, se guarda solo en esta pestaña del navegador y la comparten las dos secciones; ninguna va en la URL.

  • Preguntas sale cuando algún step tiene una pregunta. Abre Preguntas de cada step, con una fila por step: un step con una sola pregunta la enseña tal cual, y en uno con varias eliges una, cada step una distinta (por defecto, la primera aún no elegida; Restablecer vuelve a eso). Un step de respuesta dice a qué pregunta responde, y uno de lectura en silencio, de qué step sale la suya. Mientras mides o grabas, el escenario enseña la pregunta del step abierto, en el idioma hablado: Pregunta en un step de pregunta, Responde en uno de respuesta (la pregunta sigue, con la línea propia del step debajo) y Lee en silencio en uno donde la persona lee sin hablar. En una pantalla estrecha sale bajo el escenario. Si el protocolo tiene más steps que preguntas distintas, el playground dice «Hay más steps que preguntas distintas: este protocolo no se puede medir así». La misma elección llega a Engine por cada vía: con el SDK, session.step(n).start({ mediaPid }); por la API HTTP, mediaId en cada lote; en Diferido, el mediaPid de cada step en el manifiesto. El playground se guarda tu elección para sí: tu kit escribe la elección por defecto como media en neuro.config.json y KIT.md lista las opciones, así que la cambias ahí (Tu kit).
  • Idioma hablado (EN | ES; para lectores de pantalla, «Idioma hablado en la sesión») sale cuando algún step tiene preguntas o con Transcribir encendido. Es el idioma que se habla, declarado y nunca detectado: fija el idioma de la transcripción y el de las preguntas que enseña el playground. La interpretación llega en el idioma de la página. Con el Vídeo de muestra, que habla inglés, queda fijo en EN y deshabilitado («El vídeo de muestra habla inglés»); con la Cámara empieza en el idioma de la página y lo eliges tú. Un idioma equivocado da una transcripción equivocada (Trampas conocidas).
  • Transcribir está en el menú Ajustes de la captura (⚙) de Medir, y es un interruptor junto a Grabar en Diferido. Viene encendido con steps de voz; con Measurement puedes encenderlo, pero empieza apagado porque su step no es de voz. En vivo, el SDK transcribe en tu dispositivo (abre el micrófono; con el Vídeo de muestra usa el audio del vídeo) y solo el texto va a Engine. En Diferido, el servicio de procesado transcribe en el servidor todo el audio de la grabación. Engine nunca transcribe. Si un step de respuesta acaba sin voz (por ejemplo, cerrado nada más abrirse), Engine puede saltarse la interpretación, y Diferido enseña interpretation: not-requested.

Con un protocolo cuyo contexto tiene audiencias, la barra de mandos de Medir y de Diferido enseña también Audiencia: para quién se escribe la interpretación. La lista es la de tu kit para ese protocolo (las audiencias de su contexto y de su indicador objetivo); la de por defecto va marcada «por defecto», y las fijadas para tu organización, «fijada para tu organización». Empieza en la fijada para tu organización; si no hay, en la de por defecto; si el contexto no marca ninguna por defecto, en Sin indicar (no se envía audience: Engine aplica la suya). Con una sola audiencia, si es la de por defecto, sale fija; sin audiencias, o con Measurement, no sale. Como los demás mandos, la elección es por protocolo, se guarda solo en esta pestaña, la comparten las dos secciones y nunca va en la URL.

El playground fija la elección en la persona de prueba al inscribirla, con PATCH /users/{externalId} y audience cuando difiere de la que ya tiene la persona (una fila en el panel de llamadas, Fijar la audiencia de la persona); con la de por defecto o Sin indicar, envía audience: null. Es el mismo campo que envías en tu integración, en POST /users o en PATCH /users/{externalId}. La tarjeta del resultado dice después para quién se escribió la lectura: Lectura para la audiencia que aplicó Engine (audience_applied), o Lectura por defecto cuando no se envió ninguna. Una audiencia fuera de tu kit responde playground.bad_audience; cambiarla mientras una grabación en diferido de la misma persona sigue procesándose responde playground.audience_busy (espera a que acabe o cancélala en Diferido). Las opciones dependen del indicador objetivo del kit (taxonomy.hciId): sin él, solo se ofrecen las audiencias del contexto.

Ir y volver, y tus sesiones de las últimas 24 h

Sección titulada «Ir y volver, y tus sesiones de las últimas 24 h»
  • De Medir a Baseline, y de vuelta. Si llegas a Baseline desde Medir (por ejemplo, desde el diálogo que propone capturar el baseline antes de medir), una franja dice Vienes de Medir: «Captura el baseline y vuelve: tu configuración de Medir sigue igual.». Mientras se captura, dice que podrás volver al terminar. Al acabar, dice cómo quedó: Baseline listo, Calidad insuficiente (Engine lo aplicará igual; Medir con este), Pendiente o que la captura falló (Medir sin baseline). Volver y medir te deja en Medir con el foco en su botón Medir y nunca empieza a medir: Medir lo pulsas tú. Si cambias la persona, la Vía o el Origen, la franja se quita, porque Medir ya no es como la dejaste.
  • De Resultados a Medir. Si llegaste a Resultados desde Medir, Volver a Medir te devuelve (con el Atrás del navegador cuando la entrada anterior es Medir).
  • De dónde viene lo que ves. Resultados abre con una franja que lo dice: Ejemplo grabado (no es tu sesión), Tu sesión (en curso o terminada a una hora, con su persona y cuándo se borra), Sesión de las 13:10, por ejemplo (una que elegiste, con Volver a la última) o Sesión recuperada.
  • Tus sesiones de las últimas 24 h. Con sesión iniciada y un equipo con key activa, el selector Sesión de Resultados abre Tus sesiones · últimas 24 h: las de tu cuenta, agrupadas por persona de prueba, cada una con su hora, si fue en vivo (por el SDK o la API HTTP) o en diferido, sus steps y su duración, el baseline, para quién se escribió la lectura y si se interpretó. La última es lo que enseña Resultados sin elegir nada: lo último que mediste en esta pestaña, la sesión recuperada al recargar o, sin ninguna de las dos, el ejemplo grabado; sigue a Medir. Sin sesiones, o con una sola que ya es la última, el selector no se abre: es un texto fijo. La i explica que las personas del playground se borran a las 24 h, y con ellas sus sesiones. Si la sesión que estás viendo se borra (a las 24 h, o con Borrar ahora), la barra de estado lo dice y Resultados vuelve a la última o al ejemplo grabado. Solo salen las sesiones de tu equipo actual: si cambias de equipo, las de antes no aparecen, y se borran igual a las 24 h. Un diferido que sigue procesándose sale como Procesando y no se puede elegir hasta que termine.
  • Qué se relee. Elegir una sesión la vuelve a pedir a Engine (GET /results) y la guarda solo en la memoria de la pestaña: al cerrarla no queda nada. El servidor de DevLab solo guarda, por sesión, la hora, la audiencia, la vía y cómo terminó, sin texto (Tu cuenta de DevLab). La interpretación solo se relee si quedó completa o si Engine seguía interpretándola cuando el SDK (o el playground, por la API HTTP) dejó de esperar (un 202 sale como «interpretando»), y siempre con la audiencia con la que se escribió (audience en el cuerpo de POST /analyze, nunca reAnalyze): así sale de la caché de Engine y no se genera ni se paga otra. Measurement no tiene interpretación. Si la sesión no terminó completa, o no se sabe para qué audiencia se leyó (por ejemplo, porque la persona tiene ahora otra), Resultados dice que la interpretación no se relee aquí. Los recuentos que salen de las llamadas solo se conocen en la sesión activa, y en las demás salen como «—».
  • Al recargar. Si recargas la página con tu persona de prueba aún viva, la tarjeta de Medir dice Recuperando… y después Sesión recuperada: la última sesión de esa persona que se puede elegir, releída de Engine, con Lo que dijo cuando Engine lo devuelve. Si Engine no responde, dice Sin recuperar, con Reintentar. Empezar a medir, Persona → Nueva o Borrar ahora la sustituyen. Una grabación en diferido más reciente que sigue procesándose no cuenta como La última: la recuperada es la última que ya tiene resultados, y cuando ese diferido termina no se recupera sola (elígelo en el selector).
  • Un protocolo sustituido por una versión nueva. Cuando un protocolo tiene una versión nueva, la anterior queda archivada y sale de tu catálogo. Si el playground aún la tenía elegida, Medir, Diferido y SDK y API dicen que puede haber una versión nueva y que recargues la página.

El playground limita cuánto puede durar una captura, para que una prueba nunca siga sin fin (con varios steps, el Vídeo de muestra va en bucle mientras un step sigue abierto):

  • 1 min por step sin máximo propio. Un step al que el protocolo no le pone máximo se cierra solo a 1 min (o en su mínimo, si es mayor), en Medir (por el SDK y por la API HTTP) y en Diferido. Mientras está abierto, el pie del escenario dice, por ejemplo, «Se cierra solo en 18 s · tope del playground». Un step con máximo propio lo conserva, aunque pase de 1 min, y no lleva aviso. Siguiente step (o Parar en el último) lo sigue cerrando antes.
  • 10 min por sesión. Si un protocolo puede durar más de 10 min (sumando el máximo de cada step, o 1 min en los que no lo tienen), Medir y Grabar salen deshabilitados con, por ejemplo, «En el playground, una sesión no puede pasar de 10 min; este protocolo puede durar hasta 12 min.». Si aun así una sesión llega a los 10 min con un step abierto, se detiene: «La sesión llegó a los 10 min, el máximo del playground: se detuvo.». En Diferido, «La grabación llegó a los 10 min, el máximo del playground: se detuvo y no se subió.». La espera de los resultados tras el último step no cuenta. Por el SDK, detenerla cancela la sesión en Engine; por la API HTTP, se queda abierta hasta que Engine la abandona.

Con la pestaña en segundo plano, el navegador ralentiza sus temporizadores, y un step o una sesión pueden cerrarse hasta cerca de un minuto más tarde.

Son reglas del playground, no de Engine ni del SDK: en tu integración, las duraciones las decides tú. El código que enseña SDK y API, y los starters, no tienen ese tope.

No hace falta cámara: un <video> de una persona que lo aceptó es una fuente completa. Dale su src antes de capturar:

JavaScript
const video = document.querySelector('video')
video.muted = true
video.playsInline = true
video.src = '/fixtures/face.mp4'
const session = await client.captureProtocol({ userProtocolId, protocolMechanicId, source: { type: 'video', el: video }, onStarted: () => video.play() })

Para usar el mismo vídeo en varios steps, ponle loop al <video> (o rebobínalo antes de cada step.start()); si el vídeo termina con un step abierto, el step se cierra y llega el aviso source.ended.

Con la API HTTP puedes enviar frames sin ningún navegador. La captura de muestra es sintética: una malla facial genérica, la cara de nadie, diez lotes para un step. La vía cURL del Quickstart la envía.

Chrome puede servir un fichero de vídeo como cámara. Con Playwright:

JavaScript
import { chromium } from 'playwright'
const browser = await chromium.launch({ channel: 'chrome', args: ['--use-fake-ui-for-media-stream', '--use-fake-device-for-media-stream', '--use-file-for-fake-video-capture=face.y4m'] })

El .y4m es tuyo, de una persona que lo aceptó; mantenlo fuera de git. Usa channel: 'chrome', como nuestro propio E2E: un Chromium sin códecs propietarios no puede grabar H.264, y el modo diferido fallaría con E_RECORDER_UNSUPPORTED.

409 PROTOCOL_NOT_ANALYSED: pide a POST /analyze una captura de Measurement. E_RESULTS_TIMEOUT: baja outcomeDeadlineMs en el cliente. E_STEP_DURATION: stepDurations: 'enforce' y un step más corto que su mínimo. E_RECORDER_UNSUPPORTED: graba en Firefox, que no graba MP4/H.264. Errores de subida: para tu receptor (E_UPLOAD_NETWORK) o devuelve false desde checkManifest (el receptor responde 403; E_UPLOAD_REJECTED).

Firma un evento sintético con tu secreto de webhook y envíalo a tu ruta (el contrato). El formato de la firma está documentado ahí.