# Mostrar y aprovechar los resultados

Qué enseñar y hacer con cada pieza; qué es cada campo: [HCIs y resultados](/docs/es/concepts/results/).

## En resumen

- Llegan primero los indicadores; si el protocolo se interpreta, luego una lectura para una audiencia.
- Enseña primero los indicadores; la lectura, salvo si falló (con un aviso si es parcial).
- La lectura acompaña; nunca la uses por sí sola para decidir sobre la persona.
- Pueden faltar piezas: Measurement no se interpreta, lo que dijo la persona solo llega hoy en el Engine de pruebas y algunos campos son Preview.
- Construye solo sobre lo documentado.

## Qué llega, por qué vía y cuándo

| Qué | SDK · en la página | SDK · en tu backend | API HTTP · ruta |
| --- | --- | --- | --- |
| Indicadores | `onResult` (`hcis`, `hcisByStep`, `frameCount`, `raw`); `CaptureOutcome` al resolver `stop()` | `getResults(pair)`, `getProtocolResults` | `GET /results/{userProtocolId}/{protocolMechanicId}` |
| `speech` | Solo dentro de `raw` | `getResults().speech` (`null` sin el bloque) | El mismo `GET /results` |
| Interpretación | `onInterpretation` y luego `onInterpretationDetails`; `CaptureOutcome.interpretation` y `.structured` | Nada en vivo (la página te envía `metadata.status` y `audience_applied`); luego, `admin.analyze` | `constellation.complete` en `GET /stream/{userProtocolId}` y luego `POST /analyze` ([paso 6](/docs/es/api/#6-espera-la-interpretación)) |
| Informe del dispositivo | `onReport` (`SessionReport`, también con `endedBy: 'abort'` o `'error'`; no en `CaptureOutcome`) | Nada | Nada |
| Diferido (Preview) | Nada | Tras `succeeded`: `getResults`, y `admin.analyze` según `ProcessorInterpretation` | Las mismas rutas |

`onResult` llega antes de que `stop()` se resuelva, que por defecto (`'engine'`) espera la interpretación: pinta los indicadores con él ([El resultado](/docs/es/sdk/on-device/#el-resultado)). El SDK espera hasta `analyzeTimeoutMs` ([Tiempos de espera](/docs/es/guides/timeouts/#en-resumen)) y un trabajo diferido 300 s por defecto ([La interpretación](/docs/es/sdk/processing/#la-interpretación)).

## Qué enseñar primero

1. **Los indicadores, al llegar**: solo los públicos que te llegan ([dependen de tu contexto](/docs/es/resources/pitfalls/#pf-hci-not-in-your-context)), por su clave ([la tabla](/docs/es/concepts/results/#human-context-indicators)); nunca Motivation (`faa`, no válida); los cuatro que necesitan sesiones previas, como bloqueados.
2. **Luego `metadata.status`**: `complete`; si la interpretación llega `degraded`, con aviso; `failed` nunca como resultado (`E_ANALYSIS_FAILED` en la página; `E_ENGINE_HTTP` desde `admin.analyze`). Los indicadores valen igual ([la trampa](/docs/es/resources/pitfalls/#pf-interpretation-status)).
3. **El resumen**: `structured_data.insight`, si no `structured_data.headline`, si no la primera de `sections[]`.
4. **La lectura, uno de los dos**: `sections[]` (por `key`, nunca por `title`) o el Markdown de `interpretation`, sin HTML crudo.
5. **Un índice de 0 a 100**, si el dominio lo tiene: `readScoreIndex` sobre `structured`; `value` y `label` tal cual, ningún número con `status: 'not_shown'`, `degraded` como menos fiable.
6. **Para quién se escribió**: `audience_applied` (en el backend, `AnalyzeResult.audienceEvidence.audienceApplied`) o «lectura por defecto»; un eco, no una prueba.
7. **Los campos Preview**, solo si llegan: `primary_emotion.term` (un término del catálogo en inglés); `selected_ehcis[]` primero entre los indicadores, solo los públicos (un Relevante puede no estar en tu `/results`), nunca Motivation (`faa`) ni los cuatro que necesitan sesiones previas, según [la regla](/docs/es/concepts/results/#campos-en-preview); `pairs[]`, más abajo.

Su forma:

```json at="body.structured_data"
{
  "insight": null,
  "primary_emotion": { "term": "<text>" },
  "selected_ehcis": [{ "id": "coherence", "measured_value": "<number>" }]
}
```

### Solo lo que está documentado

La respuesta trae más campos de los documentados, salvo los [campos en Preview](/docs/es/concepts/results/#campos-en-preview), y más de `metadata` que `status`; no están prometidos y pueden cambiar: no construyas sobre ellos ni los enseñes.

## Qué llega y qué no

Si falta un campo, enseña lo de la última columna.

| Campo | Cuándo llega | Cuándo no llega | Qué enseñar en su lugar |
| --- | --- | --- | --- |
| Indicadores, por step y por frame | Cuando la captura está completa, en todos los modos. | Antes (`rawResults: {}`); las que tu contexto no incluye; Workload y Motivation en su calentamiento (`null`); cuatro nunca llegan. | Relee más tarde; una clave que falta es un hueco, no un cero; los cuatro, bloqueados. |
| `speech.questionText` | En el step de la pregunta, en el idioma de la narrativa; no depende de los indicadores de tu contexto. | Una persona sin idioma de narrativa; un step sin pregunta; fuera del Engine de pruebas (`speech: null`); la ruta de interrupciones. | La pregunta que enseñaste, en el idioma hablado. |
| `speech.transcript` | En el step donde se dijo, tal como lo envió tu app; solo en el Engine de pruebas. | Mira [La transcripción](/docs/es/guides/show-results/#la-transcripción). | Por qué no hay nada, nunca una caja vacía. |
| `metadata.status` | `complete`, `degraded` o `failed`; en diferido, antes la `interpretation` del trabajo (`ready`, `degraded`, `failed`, `timeout`, `unknown`, `not-requested`). | Measurement o `triggerAnalysis` apagado (`results.ready` dice por qué en `reason`: `protocol_not_interpreted` o `analysis_not_requested`), o Engine la omitió (un step de respuesta sin habla: `not-requested`). | Solo los indicadores. |
| `insight`, `headline`, `sections[]` | En la interpretación. | `insight` puede ser `null`, algunas no tienen `headline`; `CaptureOutcome.structured` es `null` con `interpretation: 'stream'`; `202 ANALYSIS_IN_PROGRESS`; `E_INTERPRETATION_TIMEOUT`. | El resumen, como arriba; con `202`, espera (`constellation.complete` o `retryAfterSeconds`); con un timeout, los indicadores y luego una lectura desde tu backend. |
| `audience_applied` | En la raíz de `/analyze`: la audiencia efectiva (la pedida o, si no, la de la persona); en vivo, en el `raw` del evento si Engine la envía. | `null` si no hay ninguna (ni pedida ni en la persona); ausente del evento de la página si Engine no la envía. | La que fijaste en la persona, o «lectura por defecto». |
| Un índice de 0 a 100 | Solo en dominios que lo publican (`wellness_index` es uno), cada uno con su clave, con `readScoreIndex`. | Otros dominios; interpretaciones guardadas antes (`from_cache: true`); `GET /analyze/lite`; `status: 'not_shown'`. | Ningún número. |
| `primary_emotion.term` · Preview | En algunas interpretaciones, un término del catálogo en inglés; solo visto en el Engine de pruebas. | En el resto; puede cambiar o desaparecer. | Nada: la página funciona sin él. |
| `selected_ehcis[]` · Preview | En algunas interpretaciones, en el orden del contexto, cada `id` con `measured_value` (toda la sesión). | En el resto; ids que no son indicadores públicos, Motivation o los cuatro que necesitan sesiones previas. | Los indicadores públicos que elijas, sin esos. |
| `pairs[]` · Preview | En algunas interpretaciones: `index`, `status` y los órdenes de `windows.opening` y `windows.closing`. | En el resto; un par que no es `complete` o cuyos órdenes no están en tus resultados. | Agrupa desde `speech` (sección siguiente). |

`session.effective_active_attention` puede llegar `null` justo tras el Final: relee `/results` ([`session`](/docs/es/concepts/results/#session)).

¿Por qué Measurement no tiene interpretación? Su kit lleva `triggerAnalysis: false` y `/analyze` responde `409 PROTOCOL_NOT_ANALYSED` ([Measurement](/docs/es/guides/measurement/)).

## Por step o por pregunta

¿Cómo agrupo los steps por pregunta? Los indicadores y `speech` llegan por step; una pregunta puede abarcar dos steps (la respuesta, en el de `media_from: previous_step`). El playground agrupa como este código: primero por `pairs[]` (los `complete` o los `incomplete` con la nota `question_from_preceding_step`: la pregunta es el step anterior); los steps que ningún par cubre, por `speech` (un step con `questionText` toma el siguiente, n+1, como respuesta si ese solo tiene `transcript` o repite la pregunta). Con pares pero sin `speech`, los papeles son apertura y cierre, no pregunta y respuesta.

`pairs[]` es Preview y `speech` solo llega en el Engine de pruebas: la página debe funcionar por step sin ellos. Su forma: [`speech`](/docs/es/concepts/results/#speech) y [`pairs[]`](/docs/es/concepts/results/#campos-en-preview).

```js
// Groups one session's steps by question. pairs: structured_data.pairs of POST /analyze
// (Preview); speech: from GET /results; orders: the steps read, e.g.
// Object.keys(aggResults). Each group: steps (order and role: question, answer, opening,
// closing or single), questionText, transcript and answerOrder (the answer's step).
export function groupByQuestion({ pairs = [], speech = null, orders }) {
  orders = orders.map(Number)
  const ok = (x) => Number.isInteger(x) && x >= 1
  const have = new Set(orders), used = new Set(), out = []
  const sp = (o) => speech?.[String(o)] ?? {}
  const st = (order, role) => ({ order, role })
  const add = (steps, questionText, transcript, answerOrder) =>
    out.push({ steps, questionText, transcript, answerOrder })
  for (const p of Array.isArray(pairs) ? pairs : []) {
    const c = p?.windows?.closing?.order
    const prev = p?.status === 'incomplete' && ok(c) && c > 1 &&
      Array.isArray(p.notes) && p.notes.includes('question_from_preceding_step')
    const o = prev ? c - 1 : p?.windows?.opening?.order
    if (!ok(p?.index) || (!prev && p.status !== 'complete')) continue
    if (!ok(o) || !ok(c) || o > c) continue
    if (!have.has(o) || !have.has(c) || used.has(o) || used.has(c)) continue
    used.add(o); used.add(c)
    const roles = speech ? ['question', 'answer'] : ['opening', 'closing']
    add([st(o, roles[0]), st(c, roles[1])],
      sp(o).questionText ?? null, sp(c).transcript ?? null, c)
  }
  const rest = speech ? orders.filter((o) => !used.has(o)).sort((a, b) => a - b) : []
  for (let k = 0; k < rest.length; k++) {
    const o = rest[k], next = rest[k + 1], q = sp(o).questionText, t = sp(o).transcript
    if (q && (t || orders.length === 1)) add([st(o, 'single')], q, t ?? null, o)
    else if (q && next === o + 1 && ((sp(next).transcript && !sp(next).questionText) ||
        sp(next).questionText === q)) {
      add([st(o, 'question'), st(next, 'answer')], q, sp(next).transcript ?? null, next)
      k++
    } else if (q) add([st(o, 'question')], q, null, null)
    else if (t) add([st(o, 'answer')], null, t, o)
  }
  out.sort((a, b) => a.steps[0].order - b.steps[0].order)
  return out.map((g, i) => ({ n: i + 1, ...g }))
}
```

## La transcripción

¿Dónde está la transcripción de lo que dijo la persona? En el campo `speech["n"].transcript` de `/results`: por step, lo que envió tu app, hoy solo en el Engine de pruebas: fuera, `getResults` da `speech: null`; `{}` es que ningún step tuvo pregunta ni transcrito. Unidos, los steps no son el texto entero ([la trampa](/docs/es/resources/pitfalls/#pf-transcripts-not-full-text)).

¿Por qué un step vuelve con la pregunta, sin lo que se dijo?

- API HTTP: nada transcribe; tu backend envía `sttByStep` ([Envía la transcripción](/docs/es/api/#envía-la-transcripción)).
- Transcripción apagada: `transcribe: false`, sin `transcribe` en kit ni código, o `transcribeSteps` deja fuera el tipo del step.
- El dispositivo no puede: [el aviso `stt`](/docs/es/guides/csp-transcription/#cuando-el-dispositivo-no-puede-transcribir) y su `blocker`.
- La CSP bloquea el worker de voz (`workerBlockedByCsp`).
- Silencio: el step en `transcription.stepsTranscription` de `onReport` tiene `transcribed: false` o `emitted: 0`.
- Idioma hablado equivocado: traducido o vacío, no ausente ([la trampa](/docs/es/resources/pitfalls/#pf-transcription-wrong-language)).
- Lo dicho fuera de todo step; un diferido sin transcripción.

El transcrito es de la persona: enséñalo solo a ella (o a quien diga tu consentimiento), nunca en logs, analítica ni fixtures ([Privacidad](/docs/es/resources/privacy/)).

## Qué guardar y cómo releer sin pagar

Guarda con tu usuario: el par (`userProtocolId`, `protocolMechanicId`) y tu `externalId` opaco, nunca el email ([Guarda el par](/docs/es/sdk/results-backend/#guarda-el-par)); la audiencia de la persona (o ninguna) y el idioma hablado declarado; y `metadata.status` y `audience_applied` (en vivo, de tu página; en el backend, en `AnalyzeResult`). Engine guarda los resultados hasta `DELETE /users/{externalId}`.

Relee sin pagar una interpretación, desde tu backend: `admin.analyze(pair, { audience })` solo si la guardada salió `complete`, con su `audience_applied` (o, si no llegó, la que fijaste en la persona), sin `reAnalyze`: `from_cache: true`; por HTTP, `POST /analyze` con `audience` y sin `reAnalyze`. Sin `audience`, Engine usa la actual de la persona y, si cambió, genera y cobra otra; con `audience_applied` `null`, omite `audience` solo mientras la persona siga sin ella. `degraded` o `failed`: cada llamada la regenera; una vez, no en bucle.

- `fromCache: null` es que Engine no envió el dato (`/analyze/lite` y `/analyze/stream` nunca), no «recién generada».
- `client.analyze` no admite `audience`: relee desde tu backend. Un `202` da `interpretation: null` y `inProgress: true`: «interpretando» ([reintenta](/docs/es/sdk/errors/#el-202-de-la-interpretación)).
- `reAnalyze` solo por una decisión, desde tu backend: cada uno se cobra ([Pedir una interpretación nueva](/docs/es/concepts/results/#pedir-una-interpretación-nueva)).

## Qué puedes construir

- Una serie por step desde `rawResults`, dentro del `raw` de `onResult`, por `timestamp`, con huecos si falta una clave.
- Otra audiencia para la sesión, sin volver a medir (`admin.analyze(pair, { audience: 'other' })` o `analyzeForAudiences`): la primera petición de cada audiencia cobra una interpretación entera; una etiqueta desconocida se acepta sin error y se cobra ([la trampa](/docs/es/resources/pitfalls/#pf-audience-unvalidated)).
- Nada con los cuatro que necesitan sesiones previas (ninguna ruta los devuelve; como mucho bloqueados, [por qué](/docs/es/concepts/results/#indicadores-que-necesitan-sesiones-previas)) ni con [lo que Engine no da](/docs/es/concepts/results/#qué-no-devuelve-engine).

> **Uso responsable**
>
> - La lectura está pensada para acompañar a la persona y nunca debe usarse por sí sola para decidir sobre ella.
> - No diagnostica, no detecta mentiras ni compara o clasifica personas.
> - Tu app informa a la persona y recoge su consentimiento.

> [Medir](/playground#measure) enseña la respuesta entera y [Resultados](/playground#results) (con sesión) la vista por rango ([El playground en DevLab](/docs/es/start/testing/#el-playground-en-devlab)).
