Protocol instance & hooks

Install, init, and walkthrough examples live in Overview & setup. This page is the reference for the ProtocolInstance methods, the useProtocol React hook, and the values they return.

Protocols drives protocol navigation — which question is current, whether the visitor can continue, and eligibility. The question’s inputs and the visitor’s answers are owned by Forms: render and store each answer on the form field whose protocolFieldId the protocol reads, and the protocol reads it back. Connect a ready-made protocol with em protocol connect.

ProtocolInstance

initProtocols({ core }).initProtocol({ protocol, forms }) returns a ProtocolInstance. Every method reads the forms’ current values at call time — there is no form-data argument and no subscribe().

string

Id of the protocol’s first medical-intake question.

ProtocolQuestion | undefined

The question definition for an id, or undefined when the id is unknown.

boolean

Whether the question should be shown, given the forms’ current values.

ContinueStatus

Whether the visitor can continue past this question — see ContinueStatus.

string | null

The next visible question id, or null at the end of the medical intake.

string | null

The previous visible question id, or null at the start.

boolean

Whether the visitor has answered enough to begin the medical intake.

EligibilityResult

The eligibility outcome — see EligibilityResult.

shouldShowQuestion, getContinueStatus, and the next/prev navigation methods throw UnknownQuestionError when passed a question id that is not in the protocol — branch on its .questionId if you accept ids from outside the protocol’s questions. getQuestionById returns undefined instead of throwing.

React

Register Protocols on EmbeddablesProvider with protocols(), then drive navigation with useProtocol. Put protocols() after forms() in modules — Protocols reads the Forms client at init.

protocols()

protocols() is the module factory for EmbeddablesProvider’s modules prop — not a hook.

import { EmbeddablesProvider } from '@embeddables/core/react'
import { forms } from '@embeddables/forms/react'
import { protocols } from '@embeddables/protocols/react'

<EmbeddablesProvider
  config={config}
  modules={[forms(), protocols({ protocols: [myProtocol] })]}
>
  {children}
</EmbeddablesProvider>

readonly Protocol[]

Protocol definitions to register (from embeddables/_dist after em protocol connect).

readonly string[]

Optional. Form ids whose fields protocols may read via protocolFieldId. When omitted, every form registered through forms() is composed in.

useProtocol()

useProtocol({ protocolId }) from @embeddables/protocols/react mirrors useForm’s no-type-argument ergonomics. It owns the current question as hook-local state and recomputes derived values on every render after any composed form changes.

string

required

Id of a protocol registered through protocols(). Throws if protocols() was not registered or the id is unknown.

It returns:

Field	Type	Description
`instance`	`ProtocolInstance`	Direct access to every instance method for arbitrary question ids
`currentQuestionId`	`string \| null`	The hook’s current question id
`question`	`ProtocolQuestion \| undefined`	The current question definition
`shouldShowQuestion`	`boolean`	Whether the current question should be shown
`continueStatus`	`ContinueStatus \| null`	Continue status for the current question (`null` until Core is ready)
`canStartMedicalIntake`	`boolean`	Whether the visitor can begin the intake
`eligibility`	`EligibilityResult \| null`	The current eligibility outcome (`null` until Core is ready)
`goToNextQuestion()`	`() => void`	Advance to the next visible question
`goToPreviousQuestion()`	`() => void`	Go back to the previous visible question
`goToQuestion(id)`	`(id: string) => void`	Jump to a specific question

For visitor or project id in React, use Core’s useAppUserId and useEmbeddablesProjectId. For form values and inputs, use Forms’ useForm / useFormField — Protocols reads those same forms.

Result types

The two values you branch on while driving protocol navigation.

ContinueStatus

Returned by getContinueStatus(id) and the hook’s continueStatus:

{ status: 'can_continue' } | { status: 'no_reply' } | { status: 'disqualified' }

EligibilityResult

Returned by isEligible() and the hook’s eligibility:

{
  status: 'qualified',
  modality: 'async',
  statusReasons: [],
  eligibleProducts: ['product_a'],
}

EligibilityStatus

required

qualified, qualified_for_eligible_products, disqualified, or pending.

EligibilityModality

sync or async — present on qualified outcomes, omitted for disqualified / pending.

string[]

required

Human-readable reasons behind the status.

string[]

Optional product ids the visitor qualifies for.

Errors

All SDK errors extend ProtocolsError.

When	Error
Invalid Core instance at init	`ProtocolsError` (thrown)
Invalid protocol at init	`ProtocolSchemaError` (thrown)
React init with a protocol configured but no `forms()` before `protocols()`	`ProtocolsError` (thrown)
Unknown protocol id	`UnknownProtocolError` (thrown)
Unknown question id passed to `shouldShowQuestion`, `getContinueStatus`, or a navigation method	`UnknownQuestionError` (thrown; branch on `.questionId`)

Get Started

SDKs

ProtocolInstance

React

protocols()

useProtocol()

Result types

ContinueStatus

EligibilityResult

Errors

​ProtocolInstance

​React

​protocols()

​useProtocol()

​Result types

​ContinueStatus

​EligibilityResult

​Errors

ProtocolInstance

React

protocols()

useProtocol()

Result types

ContinueStatus

EligibilityResult

Errors