Ir al contenido
DevLab

Mostrar y aprovechar los resultados

Qué enseñar primero cuando llegan los indicadores y la interpretación, qué llega en cada caso, dónde está el transcrito, qué guardar y cómo releer sin pagar.

En esta página
  1. En resumen
  2. Qué llega, por qué vía y cuándo
  3. Qué enseñar primero
  4. Solo lo que está documentado
  5. Qué llega y qué no
  6. Por step o por pregunta
  7. La transcripción
  8. Qué guardar y cómo releer sin pagar
  9. Qué puedes construir

Qué enseñar y hacer con cada pieza; qué es cada campo: HCIs y resultados.

  • 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é 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)
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). El SDK espera hasta analyzeTimeoutMs (Tiempos de espera) y un trabajo diferido 300 s por defecto (La interpretación).

  1. Los indicadores, al llegar: solo los públicos que te llegan (dependen de tu contexto), por su clave (la tabla); 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).
  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; pairs[], más abajo.

Su forma:

JSON
{
"insight": null,
"primary_emotion": { "term": "<text>" },
"selected_ehcis": [{ "id": "coherence", "measured_value": "<number>" }]
}

La respuesta trae más campos de los documentados, salvo los 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.

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

Qué llega y qué no, campo a campo
CampoCuándo llegaCuándo no llegaQué enseñar en su lugar
Indicadores, por step y por frameCuando 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.questionTextEn 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.transcriptEn el step donde se dijo, tal como lo envió tu app; solo en el Engine de pruebas.Mira La transcripción.Por qué no hay nada, nunca una caja vacía.
metadata.statuscomplete, 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_appliedEn 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 100Solo 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 PreviewEn 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[] PreviewEn 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[] PreviewEn 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).

¿Por qué Measurement no tiene interpretación? Su kit lleva triggerAnalysis: false y /analyze responde 409 PROTOCOL_NOT_ANALYSED (Measurement).

¿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 y pairs[].

JavaScript
// 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 }))
}

¿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).

¿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).
  • 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 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).
  • 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).

Guarda con tu usuario: el par (userProtocolId, protocolMechanicId) y tu externalId opaco, nunca el email (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).
  • reAnalyze solo por una decisión, desde tu backend: cada uno se cobra (Pedir una interpretación nueva).
  • 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).
  • Nada con los cuatro que necesitan sesiones previas (ninguna ruta los devuelve; como mucho bloqueados, por qué) ni con lo que Engine no da.