Show and use the results
What to show first when the indicators and the interpretation arrive, what arrives in each case, where the transcript is, what to keep and how to read again without paying.
What to show and do with each piece of the response; what each field is: HCIs and results.
In short
Section titled “In short”- The indicators arrive first; an interpreted protocol then adds a written reading for an audience.
- Show the indicators first; the reading, unless it failed (with a notice if it is partial).
- The reading supports the person; never use it on its own to decide about them.
- Some pieces can be missing: Measurement is not interpreted, what the person said arrives only in the test environment’s Engine today, and some fields are Preview.
- Build only on what is documented.
What arrives, by which way and when
Section titled “What arrives, by which way and when”| What | SDK · in the page | SDK · in your backend | HTTP API · route |
|---|---|---|---|
| Indicators | onResult (hcis, hcisByStep, frameCount, raw); CaptureOutcome when stop() resolves |
getResults(pair), getProtocolResults |
GET /results/{userProtocolId}/{protocolMechanicId} |
speech |
Only inside raw |
getResults().speech (null without the block) |
The same GET /results |
| Interpretation | onInterpretation, then onInterpretationDetails; CaptureOutcome.interpretation and .structured |
Nothing live (the page sends you metadata.status and audience_applied); later, admin.analyze |
constellation.complete on GET /stream/{userProtocolId}, then POST /analyze (step 6) |
| Device report | onReport (SessionReport, also on endedBy: 'abort' or 'error'; not in CaptureOutcome) |
Nothing | Nothing |
| Deferred (Preview) | Nothing | After succeeded: getResults, and admin.analyze by ProcessorInterpretation |
The same routes |
onResult comes before stop() resolves, which by default ('engine') waits for the interpretation: draw the indicators from it (The outcome). The SDK waits up to analyzeTimeoutMs (Timeouts) and a deferred job 300 s by default (The interpretation).
What to show first
Section titled “What to show first”- The indicators, on arrival: only the public ones that reach you (they depend on your context), by their key (the table); never Motivation (
faa, not valid); the four that need previous sessions, as locked. - Then
metadata.status:complete; if the interpretation arrivesdegraded, with a notice;failednever as a result (E_ANALYSIS_FAILEDin the page;E_ENGINE_HTTPfromadmin.analyze). The indicators still hold (the pitfall). - The summary:
structured_data.insight, elsestructured_data.headline, else the first ofsections[]. - The reading, one of the two:
sections[](bykey, never bytitle) or the Markdown ofinterpretation, rendered without raw HTML. - A 0 to 100 index, if the domain has one:
readScoreIndexonstructured;valueandlabelas they come, no number withstatus: 'not_shown',degradedas less reliable. - Who it was written for:
audience_applied(in the backend,AnalyzeResult.audienceEvidence.audienceApplied), else «default reading»; an echo, not proof. - The Preview fields, only if they arrive:
primary_emotion.term(an English catalogue term);selected_ehcis[]first among the indicators, public ones only (a Relevant one may not be in your/results), never Motivation (faa) nor the four that need previous sessions, matched by the rule;pairs[], below.
Their shape:
{ "insight": null, "primary_emotion": { "term": "<text>" }, "selected_ehcis": [{ "id": "coherence", "measured_value": "<number>" }]}Only what is documented
Section titled “Only what is documented”The response carries more fields than documented, Preview fields aside, and more of metadata than status: they are not promised and can change; do not build on them or show them.
What arrives and what does not
Section titled “What arrives and what does not”If a field is missing, show the last column.
| Field | When it arrives | When it does not | What to show instead |
|---|---|---|---|
| Indicators, per step and per frame | When the capture is complete, in every mode. | Before that (rawResults: {}); keys your context does not include; Workload and Motivation in their warm-up (null); four never arrive. | Read again later; a missing key is a gap, not zero; the four, locked. |
speech.questionText | In the question's step, in the narrative's language; it does not depend on your context's indicators. | A person without a narrative language; a step without a question; outside the test environment's Engine (speech: null); the interruption route. | The question you showed, in the spoken language. |
speech.transcript | In the step where it was said, as your app sent it; only in the test environment's Engine. | See The transcript. | Why there is nothing, never an empty box. |
metadata.status | complete, degraded or failed; in deferred, first the job's interpretation (ready, degraded, failed, timeout, unknown, not-requested). | Measurement or triggerAnalysis off (results.ready says why in reason: protocol_not_interpreted or analysis_not_requested), or Engine skipped it (an answer step without speech: not-requested). | The indicators only. |
insight, headline, sections[] | In the interpretation. | insight can be null, some have no headline; CaptureOutcome.structured is null with interpretation: 'stream'; 202 ANALYSIS_IN_PROGRESS; E_INTERPRETATION_TIMEOUT. | The summary, as above; on 202, wait (constellation.complete or retryAfterSeconds); on a timeout, the indicators, then read it once from your backend. |
audience_applied | At the root of /analyze: the effective audience (the one requested or else the person's); live, in the event's raw if Engine sends it. | null with neither (none requested, none on the person); absent from the page's event if Engine does not send it. | The audience you set on the person, or «default reading». |
| A 0 to 100 index | Only in domains that publish one (wellness_index is one), each under its own key, with readScoreIndex. | Other domains; interpretations stored before it (from_cache: true); GET /analyze/lite; status: 'not_shown'. | No number. |
primary_emotion.term Preview | In some interpretations, an English catalogue term; seen so far only in the test environment's Engine. | In the rest; it can change or go away. | Nothing: the page works without it. |
selected_ehcis[] Preview | In some interpretations, in the context's order, each id with measured_value (the whole session). | In the rest; ids that are not public indicators, Motivation or the four that need previous sessions. | Your own choice of public indicators, without those. |
pairs[] Preview | In some interpretations: index, status and the orders of windows.opening and windows.closing. | In the rest; a pair that is not complete or whose orders are not in your results. | Group from speech (next section). |
session.effective_active_attention can arrive null right after the Final: read /results again (session).
Why no interpretation in Measurement? Its kit sets triggerAnalysis: false and /analyze answers 409 PROTOCOL_NOT_ANALYSED (Measurement).
Per step or per question
Section titled “Per step or per question”How do I group the steps by question? The indicators and speech come per step; a question can span two steps (the answer in the media_from: previous_step one). The playground groups them as the code below does: first by pairs[] (complete, or incomplete noted question_from_preceding_step: the question is the step before); the steps no pair covers, by speech (a step with questionText takes the next step, n+1, as its answer if that one only has transcript or repeats the question). With pairs but no speech, the roles are opening and closing, not question and answer.
pairs[] is Preview and speech only in the test environment’s Engine: the page has to work per step without them. Their shape: speech and 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 }))}The transcript
Section titled “The transcript”Where is the transcript of what the person said? In the field speech["n"].transcript of /results: per step, what your app sent, only in the test environment’s Engine today: elsewhere getResults gives speech: null; {} means no step had a question or a transcript. Joined, the steps are not the full text (the pitfall).
Why does a step bring the question but not what was said?
- HTTP API: nothing transcribes; your backend sends
sttByStep(Send the transcript). - Transcription off:
transcribe: false, notranscribein kit or code, ortranscribeStepsleaves out the step’s type. - The device cannot: the
sttwarning and itsblocker. - The CSP blocks the speech worker (
workerBlockedByCsp). - Silence: the step in
transcription.stepsTranscriptionofonReporthastranscribed: falseoremitted: 0. - Wrong spoken language: translated or empty, not absent (the pitfall).
- Speech outside every step; a deferred job without transcription.
The transcript belongs to the person: show it only to them (or to whom your consent says), never in logs, analytics or fixtures (Privacy).
What to keep and how to read again without paying
Section titled “What to keep and how to read again without paying”Keep with your user: the pair (userProtocolId, protocolMechanicId) and your opaque externalId, never the email (Keep the pair); the person’s audience (or none) and the declared spoken language; and metadata.status and audience_applied (live, your page sends them; from your backend, in AnalyzeResult). Engine keeps results until DELETE /users/{externalId}.
Read an interpretation again without paying, from your backend: admin.analyze(pair, { audience }) only if the stored one came out complete, with its audience_applied (or, if it did not arrive, the audience you set on the person), without reAnalyze: from_cache: true; over HTTP, POST /analyze with audience and without reAnalyze. Without audience, Engine uses the person’s current one and, if it changed, generates and bills another; with audience_applied null, omit audience only while the person still has none. degraded or failed: every call regenerates it, so once, never in a loop.
fromCache: nullmeans Engine did not send the flag (/analyze/liteand/analyze/streamnever), not «freshly generated».client.analyzetakes noaudience: read again from your backend. A202givesinterpretation: nullandinProgress: true: «interpreting» (retry).reAnalyzeonly on a decision, from your backend: each one is billed (Ask for a fresh interpretation).
What you can build
Section titled “What you can build”- A series per step from
rawResults, inside therawofonResult, sorted bytimestamp, gaps where a key is missing. - Another audience for the same session, without measuring again (
admin.analyze(pair, { audience: 'other' })oranalyzeForAudiences): each audience’s first request bills a whole interpretation, and an unknown label is accepted without error and billed (the pitfall). - Nothing on the four that need previous sessions (no route returns them; locked at most, why) or on what Engine does not give.