# Vías de integración

Recomendamos **capturar con el SDK, en el dispositivo (tiempo real)**, para la mayoría de las integraciones, y usar la **API HTTP** para lo puntual y tu backend: consultar resultados más tarde, sondear o buscar en el catálogo. Captura en **diferido (en servidor)** cuando el dispositivo no aguanta la captura en vivo (móviles modestos, sesiones largas) y puedes subir vídeo: hoy puedes grabar, subir y procesar con el servicio de procesado de Neurologyca, sin desplegar nada. Si capturas fuera del navegador (otro lenguaje u otra plataforma, o ya tienes los frames), la API HTTP también captura.

El SDK para capturar; la API para lo puntual y tu backend. Lo habitual es combinar las dos.

## El camino por defecto

Si dudas: el SDK en el dispositivo (tiempo real), con Measurement como primer protocolo (en el entorno de pruebas: el Engine de producción aún no lo ofrece ([Tus entornos](/docs/es/start/environments/))); pasa a diferido (en servidor) si tus pruebas en tus móviles lo piden. Empieza por el [Quickstart](/docs/es/start/quickstart/) y [Measurement](/docs/es/guides/measurement/).

Sin cuenta: los ejemplos grabados, el código y la doc; medir, con invitación ([solicita acceso](https://intake.neurologyca.com)).

## Dos preguntas

Decides dos cosas, y no dependen una de otra: **cómo integras** (el SDK, la API HTTP o las dos) y **dónde se procesa** (en el dispositivo o en un servidor).

- **En el dispositivo (tiempo real)**: Tu página · SDK, cliente en vivo → Tu backend · proxy (pone el token) → Engine
- **Diferido (en servidor)** (Preview): Tu página · SDK, cliente de grabación → Tu backend · receptor de subidas → Servicio de procesado (Preview) → Engine
- **API HTTP**: Cualquier lenguaje: la API HTTP, directa desde tu backend → Engine

## Cómo integras

| Tema | SDK · Recomendado para capturar | API HTTP · Complementaria | SDK + API · Lo habitual |
| --- | --- | --- | --- |
| Para qué | Para capturar: protocolo, steps, lotes, baseline y los resultados de la sesión. | Para lo puntual y tu backend: resultados más tarde, sondeo, catálogo, participantes, contextos, cualquier lenguaje. | Captura en el navegador con el SDK y consulta después desde tu backend con la API: resultados más tarde, sondeo, catálogo. Ver [Los resultados en tu backend](/docs/es/sdk/results-backend/). |
| Qué hace por ti | Las rutas, el token (lo pone tu proxy), el troceo en lotes, los reintentos, los conflictos y la reserva de la posición. | Nada: montas tú las llamadas, los lotes, los reintentos y el flujo de eventos. | El SDK hace la captura; tu backend hace lecturas sencillas. |
| Tu backend | `@neurologyca/capture-server`: el proxy (`createEngineProxy`) y `createEngineAdmin`, que es la misma API desde Node. | Cualquier lenguaje: `POST /token` con tu key y después las llamadas de la guía HTTP. | `createEngineAdmin` crea la persona y la inscripción; después, `getResults` o `GET /results`. |
| Tiempo hasta el primer resultado | Segundos después del último step: el `CaptureOutcome` llega poco después de acabar la sesión, así que un protocolo corto da su primer resultado en menos de un minuto; crear la persona y la inscripción antes de Start lleva un momento más. | Segundos después del último lote: el quickstart cURL va de `POST /token` a los resultados en bastante menos de un minuto. | Lo mismo que el SDK; tu backend lee cuando lo necesita. |
| Esfuerzo | Un fichero de backend (proxy, persona e inscripción) y una página: lo que construye el quickstart. | La guía HTTP a mano: las llamadas, los lotes, los reintentos y el flujo de eventos. | El SDK en la página y unas pocas lecturas en tu backend. |

El SDK y la API se combinan en los dos sentidos:

- **Backend primero:** `createEngineAdmin` crea la persona y la inscripción, y la página captura con ese par de ids.
- **Navegador primero:** la página captura con el SDK y tu backend lee los resultados después (`GET /results` o `createEngineAdmin().getResults`, la misma API desde Node). Ver [Los resultados en tu backend](/docs/es/sdk/results-backend/).

> Reabrir la página puede volver a inscribir a la persona. Guarda el par de ids en tu backend y usa la misma persona y el mismo origen (cámara o vídeo) para el baseline y la medición.

## Dónde se procesa

| Tema | En el dispositivo (tiempo real) · Preview 0.45 | Diferido (en servidor) · Preview | Autoalojado (próximamente) |
| --- | --- | --- | --- |
| Hoy | Disponible. | Puedes grabar, subir y procesar con el servicio de procesado de Neurologyca: nada que desplegar. | Llegará más adelante. |
| Dónde se procesa | En el navegador, en el dispositivo de la persona, mientras captura. | En nuestro servicio de procesado, poco después de subir. No son horas: simplemente no se procesa en el dispositivo. | En tus propios servidores. |
| Cuándo hay resultados | Durante la sesión y segundos después del último lote en una captura corta. Una captura larga, con miles de frames, tarda minutos. Pasado `outcomeDeadlineMs` (240 s por defecto), `stop()` da `E_RESULTS_TIMEOUT`, que no es una pérdida: lee los resultados después. | Unos minutos después de subir, sumando tres tramos: la subida (unos 7 min para 3 min de vídeo a 1,75 Mbps, un cálculo), la cola (un trabajo cada vez) y el procesado, algo más largo que el propio vídeo. | Llegará más adelante. |
| Qué sale del dispositivo | Landmarks, coeficientes de expresión y pose, hacia Engine. Solo si los activas: el transcrito (el reconocimiento de voz corre en el navegador, así que el audio se queda y el texto sale; Engine lo pasa a un LLM para la interpretación) y las señales extra (la voz como números, el pulso, las manos, el cuerpo). Nunca imagen, vídeo ni audio. | Vídeo y audio (con la cámara, el micrófono va siempre) hacia tu receptor y, de ahí, al servicio de procesado, que, con la transcripción activada, transcribe todo el audio de la grabación y solo pasa a Engine el texto de los steps que pide el trabajo (`transcribeSteps`). El audio crudo identifica a una persona más que los números, y el manifiesto que viaja con el vídeo lleva el `userAgent` completo del navegador. | Vídeo y audio, hacia tus propios servidores. |
| Qué te limita | El dispositivo: la detección de la cara en la GPU (WebGL 2) y, en móvil, el calor en sesiones largas, que bajan los fps. Un móvil o un portátil reciente suele quedarse cerca de los fps de la cámara; un móvil de gama de entrada captura menos frames por segundo, y un móvil los pierde según se calienta. | El ancho de banda de subida. A 4 Mbps, 3 min de vídeo son unos 93 MB (unos 310 MB por 10 min). La subida se reanuda tras un corte. La calidad depende del bitrate de la grabación y de la luz, no de la potencia del dispositivo: el procesado corre en el servidor. | Llegará más adelante. |
| Navegadores y móvil | Chrome y Edge 94+, Safari 16.4+ (iOS 16.4+), en escritorio y en móviles capaces. | Graba MP4/H.264: Chrome y Edge de escritorio, Chrome en Android y Safari en iOS. Un iPhone también graba MP4: su fichero puede acabar unos 1,1 s antes del stop, por eso el SDK sigue grabando 2 s más. En móvil o tableta graba en vertical: espera a que el dispositivo esté derecho. | Llegará más adelante. |
| Measurement | Sí. | Sí, desde 0.27.0: `triggerAnalysis: false` viaja en el manifiesto y el procesador no llama a `/analyze`. | Llegará más adelante. |
| Casos típicos | Un check-in corto en un portátil; una tarea de dos minutos en un móvil reciente; cualquier captura cuyo vídeo no deba salir del dispositivo. | Una entrevista de diez minutos en un móvil modesto; una sesión de campo en un dispositivo flojo, subida después. | Vídeo que debe procesarse dentro de tu propia infraestructura. |
| Pasar de uno a otro | `createProtocolClient` (de `@neurologyca/capture`) ↔ `createRecordingClient` (de `@neurologyca/capture/record`, sin kodec). Algunas opciones no pasan: `transcribe` es solo del vivo; en diferido transcribe el servicio de procesado. | Añade el receptor a tu backend (`createUploadReceiver`); graba desde la cámara, un `<video>` o un stream. | Llegará más adelante. |

Firefox no es objetivo: kodec no se ha probado allí (en el dispositivo), y no graba MP4/H.264 (en diferido).

> Las opciones no siempre pasan de un modo al otro: `transcribe` es una opción del vivo y, en diferido, transcribe el servicio de procesado. La página de cada modo dice cuáles: [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/) y [Diferido (en servidor)](/docs/es/sdk/deferred/).

## ¿Cuál elijo?

| Si… | Elige |
| --- | --- |
| tu gente usa escritorio o móviles recientes y quieres resultados durante la sesión (en capturas cortas; las largas tardan minutos en cerrarse) | **En el dispositivo (tiempo real)** |
| el vídeo no puede salir del dispositivo | **En el dispositivo (tiempo real)** |
| usas móviles modestos, sesiones de varios minutos, o el ritmo de tus sesiones queda bajo | **Diferido (en servidor)**: hoy puedes grabar, subir y procesar con el servicio de procesado de Neurologyca, sin desplegar nada. |
| no sabes qué dispositivos usará tu gente, o sus móviles son muy distintos, y quieres la calidad más estable | **Diferido (en servidor)** (Preview): el vídeo sale del dispositivo, se sube y se procesa en el servidor, así que esperas el resultado tras la subida. Tu organización tiene que tenerlo activado. |
| quieres tiempo real por defecto y una salida cuando el dispositivo no da | **En el dispositivo (tiempo real)** por defecto, y **Diferido (en servidor)** (Preview), con permiso de la persona, cuando la comprobación del dispositivo dice que no puede medir o no puede transcribir. Tu organización tiene que tenerlo activado. |
| el vídeo debe procesarse fuera del dispositivo pero dentro de tu infraestructura | **Autoalojado (próximamente)**; hasta entonces, diferido con nuestro servicio. |
| capturas en el navegador y luego consultas desde tu backend (resultados, sondeo, catálogo) | **SDK + API** (lo habitual) |
| capturas desde otro lenguaje u otra plataforma, o ya tienes los frames | **API HTTP** |
| solo quieres medir, sin interpretación | **Measurement**, en el dispositivo (tiempo real) (en diferido también, desde 0.27.0) |
| dudas | El camino por defecto: **SDK en el dispositivo, empezando por Measurement** |

Para decidir por los dispositivos de tu gente, y comprobar un dispositivo antes de medir: [Dispositivos, calidad y modo](/docs/es/start/devices-and-modes/).

## Qué decides tú y qué hace el SDK

| Tema | Tú | El SDK y `capture-server` |
| --- | --- | --- |
| **Tu pantalla**: cómo se ve todo, sus textos e idioma; el consentimiento **antes** de `captureProtocol`, y solo desde un gesto de la persona | ✔ | Abrir la cámara y el micrófono en esa llamada |
| **Por protocolo**: cuánto dura un step cuando Engine no lo dice, quién lo cierra (un tope, un botón, el final del vídeo) y qué dice un step sin texto | ✔, con los datos de `describeStep` | Comprobar cada step con el mínimo y el máximo de Engine (`stepDurations`) |
| **Por protocolo**: si la persona puede repetir una captura y qué pasa con un `409` | ✔, con `ConflictDetail` | Convertir cada `409` en una sola forma |
| **Tu backend**: autenticar a tus usuarios antes del proxy y del receptor, y qué ids puede tocar cada uno | ✔ (`authorize` con `ownsAll`, `checkManifest`) | Negarse a construirse sin ellos |
| **Tu backend**: dónde se guardan las grabaciones, cuánto se conservan las confirmadas y llamar a `sweep()` | ✔ | `storage` es obligatorio: `localDiskStorage` o el tuyo; define qué se abandona |
| **Lo que hace el SDK**: rutas de Engine, cabeceras, correlación; acuñar, cachear y poner el token | — | ✔ |
| **Lo que hace el SDK**: troceo en lotes, reintentos, reanudar una subida, la reserva de la posición y su liberación | — | ✔ |
