Integrate the SDK

Events and logging

While a session runs, Speechineer reports what it is doing as a stream of events. They reach your code through the session's onEvent callback (Integrate the SDK › Implementation › Wire up the voice session › onEvent) and are mostly informational: use them for logging or a live status display.

One shape covers everything Speechineer reports, and level is what tells you how much it matters. debug, info and warning are progress — the session carries on. error means the session is over, and nothing else does. So onEvent sees failures too: it is the one callback that sees everything, and you never have to correlate two streams to find out whether a session is still alive.

The event object

Every event is one object:

code is the stable identifier to branch on, and type groups codes into families. There are two messages, for two readers: userMessage is already translated into the session's language and is what you show a person; message is English and is what you write to a log. meta carries the detail belonging to that code — retry counters, the field a validation complaint is about, the numbers on a spent allowance.

Telling the end from the noise

If you only branch on one thing, branch on level:

onEvent: (event) => {
  // The one branch that matters: "error" means this session is finished.
  if (event.level === "error") showBanner(event.userMessage);
  else log.push(event.code, event.meta);
};

Everything below error is something you can log and move on from. Codes are stable, but new ones appear over time — so ignore a code you do not know rather than treating it as a failure.

Listen for events

Listening is a single option: you pass onEvent where you build the session, next to your other callbacks, and it is called for everything that arrives. If you only want one level, onWarning, onInfo and onDebug each receive just their own — the same objects, pre-filtered. The options are the same in every framework:

const voice = useSpeechToForm({
  form: intakeForm,
  // Everything, errors included — level says which.
  onEvent: (event) => log.push(`[${event.level}] ${event.code}`, event.meta),
  // Or just one level:
  onWarning: (notice) => log.warn(notice.code, notice.message),
});

readonly voice = injectSpeechToForm({
  form: intakeForm,
  onEvent: (event) => log.push(`[${event.level}] ${event.code}`, event.meta),
  onWarning: (notice) => log.warn(notice.code, notice.message),
});

const session = speechineer.speechToForm({
  form: intakeForm,
  onEvent: (event) => log.push(`[${event.level}] ${event.code}`, event.meta),
  onWarning: (notice) => log.warn(notice.code, notice.message),
});

What Speechineer reports

Everything below is non-terminal — the session kept running. They are grouped by what they ask of you, because that is the only question a notice raises: most ask nothing, a few point at something in your code, and the rest are configuration behind your workspace. Terminal failures are a separate list, in Integrate the SDK › Errors.