Skip to main content

Control encounters from your page

@nabla/connect-sdk is the SDK for the page that embeds the Nabla Connect iframe, also called the front integration. It lets that page follow the encounter and drive it: read the recording state, start or stop recording, generate the note, export it, and know when the iframe can safely be closed.

What the SDK does​

  • Reports the state of the encounter, and the actions the iframe accepts right now.
  • Runs commands: start or stop recording, generate the note, export it.
  • Delivers the exported note and patient instructions to your page as events.
  • Tells you when closing or navigating away loses nothing.

The SDK runs in the browser, has no runtime dependencies, and ships TypeScript declarations.

What it does not do​

  • It does not create the iframe. You render it, without a src.
  • It does not call POST /encounters. Your backend does, as described in Launch encounters.
  • It does not handle authentication. It needs no secret.

How it fits​

Your backend launches the encounter and hands the encounter URL to your page. The SDK loads that URL in the iframe, then reports state and exports. The NOTE_EXPORT callback still delivers the note to your backend. See Receive callbacks.

Requirements​

Before the SDK can work, four things must be in place. Set up the SDK walks through each one.

  1. Nabla enabled the SDK for your organization.
  2. Your page origins are in the allowlist of Nabla Connect Admin.
  3. Your backend passes target_origin when it launches the encounter.
  4. Your page renders an iframe without a src.

Security​

  • The SDK only accepts messages from the origin of the url you passed to create, and only posts to it. The iframe only accepts messages from the target_origin selected at launch. Do not relay through intermediate frames.
  • Any script on an allowlisted origin can control the encounter.
  • Keep OAuth client secrets and API keys on your backend. The SDK needs none.
  • Lifecycle messages carry no patient data. Note content only arrives on noteExported and patientInstructionsExported.

Versioning​

The package follows semver. It is in beta: the API may change before 1.0.0, so pin the version and read the changelog before you upgrade.

A newer Nabla release keeps working with an older SDK until a breaking change, which ready reports as UNSUPPORTED_VERSION. Keep the SDK updated like any dependency.

This documentation is versioned by SDK minor release. Use the version selector to read the guides and the reference of an older release.