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.
Qué enseñar y hacer con cada pieza; qué es cada campo: HCIs y resultados.
En resumen
Sección titulada «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
Sección titulada «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) |
| 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).
Qué enseñar primero
Sección titulada «Qué enseñar primero»- 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. - Luego
metadata.status:complete; si la interpretación llegadegraded, con aviso;failednunca como resultado (E_ANALYSIS_FAILEDen la página;E_ENGINE_HTTPdesdeadmin.analyze). Los indicadores valen igual (la trampa). - El resumen:
structured_data.insight, si nostructured_data.headline, si no la primera desections[]. - La lectura, uno de los dos:
sections[](porkey, nunca portitle) o el Markdown deinterpretation, sin HTML crudo. - Un índice de 0 a 100, si el dominio lo tiene:
readScoreIndexsobrestructured;valueylabeltal cual, ningún número constatus: 'not_shown',degradedcomo menos fiable. - Para quién se escribió:
audience_applied(en el backend,AnalyzeResult.audienceEvidence.audienceApplied) o «lectura por defecto»; un eco, no una prueba. - 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:
{ "insight": null, "primary_emotion": { "term": "<text>" }, "selected_ehcis": [{ "id": "coherence", "measured_value": "<number>" }]}Solo lo que está documentado
Sección titulada «Solo lo que está documentado»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.
Qué llega y qué no
Sección titulada «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. | 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).
¿Por qué Measurement no tiene interpretación? Su kit lleva triggerAnalysis: false y /analyze responde 409 PROTOCOL_NOT_ANALYSED (Measurement).
Por step o por pregunta
Sección titulada «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 y pairs[].
// 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
Sección titulada «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).
¿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, sintranscribeen kit ni código, otranscribeStepsdeja fuera el tipo del step. - El dispositivo no puede: el aviso
stty sublocker. - La CSP bloquea el worker de voz (
workerBlockedByCsp). - Silencio: el step en
transcription.stepsTranscriptiondeonReporttienetranscribed: falseoemitted: 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).
Qué guardar y cómo releer sin pagar
Sección titulada «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); 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: nulles que Engine no envió el dato (/analyze/litey/analyze/streamnunca), no «recién generada».client.analyzeno admiteaudience: relee desde tu backend. Un202dainterpretation: nullyinProgress: true: «interpretando» (reintenta).reAnalyzesolo por una decisión, desde tu backend: cada uno se cobra (Pedir una interpretación nueva).
Qué puedes construir
Sección titulada «Qué puedes construir»- Una serie por step desde
rawResults, dentro delrawdeonResult, portimestamp, con huecos si falta una clave. - Otra audiencia para la sesión, sin volver a medir (
admin.analyze(pair, { audience: 'other' })oanalyzeForAudiences): 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.