Protocols SDK

Overview

Protocols drives medical intake navigation: it walks the visitor through a protocol’s questions, decides which one to show next, and evaluates whether they can continue or are eligible. It reads answers from Forms — set up Forms first, then Protocols uses those answers as the visitor moves through the flow. Protocols also needs Core, like every other SDK. Answers are linked by each field’s protocolFieldId in your form setup. The walkthrough below covers install and wiring. When you need the full instance API, the React hook, or the protocol contract, open the reference.

How it fits together

Core initializes once, as it does for every SDK.
Forms must be set up before Protocols — Protocols reads form answers; it does not create forms.
A form field opts into protocol reads by declaring a protocolFieldId — supported on text, email, boolean, select, and multiselect fields (not number or json, which em build rejects). Protocol logic reads that value with getValueByProtocolFieldId.
When two forms declare the same protocolFieldId, the later form in the array wins.

In React, list Forms before Protocols in your modules setup (as in the example below). If Forms is missing, Protocols cannot start.

Implementation

Install

npm install @embeddables/core @embeddables/forms @embeddables/protocols

pnpm add @embeddables/core @embeddables/forms @embeddables/protocols

yarn add @embeddables/core @embeddables/forms @embeddables/protocols

Install Core and Forms first, then add Protocols.

Connect a protocol

Connect a ready-made one from the catalog with the Embeddables CLI:

em protocol connect <protocol-id>

This downloads the protocol into your project and builds it into embeddables/_dist. Import it from there and pass it to initProtocol (JavaScript) or protocols({ protocols }) (React).

Set up

With the protocol connected and Forms set up, pick your setup:

React
JavaScript

Follow the example below: enable Forms, then Protocols, in the same modules list. Form schemas live on config.forms from embeddables/_dist. Import your protocol from _dist after em protocol connect — the CLI does not plug it in automatically.

import { EmbeddablesProvider } from '@embeddables/core/react'
import { forms as formsModule } from '@embeddables/forms/react'
import { protocols, useProtocol } from '@embeddables/protocols/react'
import { config } from './embeddables/_dist'
import { myProtocol } from './embeddables/_dist/protocols/my-protocol'

function IntakeQuestion() {
  const { question, continueStatus, goToNextQuestion } = useProtocol({
    protocolId: 'my-protocol',
  })

  return (
    <div>
      <p>{question?.text}</p>
      <button
        type="button"
        disabled={continueStatus?.status !== 'can_continue'}
        onClick={() => goToNextQuestion()}
      >
        Continue
      </button>
    </div>
  )
}

export function App() {
  return (
    <EmbeddablesProvider
      config={{ ...config, publishableKey: 'pk_sandbox_<your-key>' }}
      modules={[
        formsModule(),
        protocols({ formIds: Object.keys(config.forms), protocols: [myProtocol] }),
      ]}
    >
      <IntakeQuestion />
    </EmbeddablesProvider>
  )
}

formIds: Object.keys(config.forms) composes every generated form; pass a narrower list if only some forms carry protocolFieldIds the protocol reads.useProtocol tracks the current question and whether the visitor can continue. See the reference for the full hook and navigation helpers.

After you connect a protocol, you still pass it explicitly in protocols({ protocols: [...] }), as in the example — em build does not choose the protocol for you.

Initialization is two steps: initProtocols({ core }) validates Core and returns a client, then .initProtocol({ protocol, forms }) binds your initialized form instances into a ProtocolInstance.Your form schemas — including each field’s protocolFieldId — are generated by the Embeddables CLI (em build) into embeddables/_dist. Spread config into Core so schemas register under config.forms; import the protocol from _dist rather than writing schemas by hand.

import { initEmbeddables } from '@embeddables/core'
import { initForms } from '@embeddables/forms'
import { initProtocols } from '@embeddables/protocols'
import { config } from './embeddables/_dist'
import { myProtocol } from './embeddables/_dist/protocols/my-protocol'

const core = initEmbeddables({
  ...config,
  publishableKey: 'pk_sandbox_<your-key>',
})

const formsClient = initForms({ core })

const instance = initProtocols({ core }).initProtocol({
  protocol: myProtocol,
  forms: core.getFormIds().map((formId) => formsClient.getForm({ formId })),
})

const firstId = instance.getFirstQuestionId()
const continueStatus = instance.getContinueStatus(firstId)
const eligibility = instance.isEligible()

Pass every initialized form to initProtocol once — instance methods never take a form-data argument, and they read the forms’ current values on every call.

protocolFieldId is a Forms concept: it lives on each form field in your Embeddables config and is emitted by the CLI into embeddables/_dist. The protocol never defines form schemas — it only reads values by protocolFieldId. See Forms for how schemas are generated.

Need the full instance API, the React hook, protocol-agnostic helpers, or the Protocol contract? See the reference.

Get Started

SDKs

Overview

How it fits together

Implementation

Install

Connect a protocol

Set up

​Overview

​How it fits together

​Implementation

​Install

​Connect a protocol

​Set up

Overview

How it fits together

Implementation

Install

Connect a protocol

Set up