Build a Web SDK Ambient Session

Use-case tutorial: Authenticate with SukiAuthManager, initialize the Web SDK in React, and mount SukiAssistant for an Ambient encounter

What you will build

15 min | Intermediate

• A React page wrapped with the Web SDK provider.
• One shared auth manager and a single SDK initialize call.
• The hosted ambient UI for one patient encounter with LOINC note sections.

Using an AI coding tool?

Copy the prompt below to point your agent at the Ambient skill and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the Ambient skill and connect the documentation MCP.

CopiedCopy promptOpen in Cursor

In this tutorial, you build a React ambient encounter page with the Web SDK. You install the packages, wrap the app with SukiProvider, authenticate with SukiAuthManager, call init, and mount SukiAssistant with patient encounter context.

By the end of this tutorial, you will have a working React page that signs in to Suki and opens the hosted ambient UI for one encounter.

Prerequisites

Before you begin, make sure you have:

• Completed Partner onboarding and received your partnerId and partnerToken.
• A React 18+ app that can host the Web SDK UI.
• Host URLs on the Suki allowlist and a partner JWT that meets Web SDK prerequisites.

Prefer staging credentials while you learn. Switch environment to production only when your partner configuration is ready.

Architecture

Project setup

1. Use a React 18+ app that can host the Web SDK UI (see Prerequisites).
2. Install the required dependencies. Refer to Web SDK installation.

# pnpm
pnpm add @suki-sdk/react @suki-sdk/core

# npm
npm install @suki-sdk/react @suki-sdk/core

3. Configure your credentials:.

   • Keep partnerId and partnerToken ready for SukiAuthManager (prefer staging while you learn).
   • Confirm host URLs meet Web SDK prerequisites.

Tutorial steps

Work through each step in order. Read the explanation, review the code example, then continue to the next step. The full code example is available in the accordion below.

1. Wrap Your App with SukiProvider

   In Web SDK v3, wrap your tree with SukiProvider. Run init in a child component, not on the provider.

   Check: The tree is wrapped with SukiProvider, and init runs in a child component.

   import { SukiProvider } from "@suki-sdk/react";
   
   function App() {
   return (
   <SukiProvider>
     <AmbientEncounterPage />
   </SukiProvider>
   );
   }
   
2. Create SukiAuthManager and Call Init

   Create SukiAuthManager once with useMemo, then call init with authManager from useSuki() when the SDK is not initialized yet.

   Check: init({ authManager }) runs once under SukiProvider when isInitialized is false.

   If it fails: Confirm init({ authManager }) runs once under SukiProvider when isInitialized is false.

   import { useEffect, useMemo } from "react";
   import { SukiAuthManager } from "@suki-sdk/core";
   import { useSuki } from "@suki-sdk/react";
   
   function AmbientEncounterPage() {
   const authManager = useMemo(
   () =>
     new SukiAuthManager({
       partnerId: "YOUR_PARTNER_ID",
       partnerToken: "YOUR_PARTNER_TOKEN",
       providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
       providerOrgId: "YOUR_ORG_ID",
       environment: "staging", // Example — staging | production
       loginOnInitialize: true,
     }),
   [],
   );
   
   const { init, isInitialized } = useSuki();
   
   useEffect(() => {
   if (!isInitialized) {
     init({ authManager });
   }
   }, [init, isInitialized, authManager]);
   
   return null;
   }
   
3. Mount SukiAssistant with Encounter and Sections

   Pass a valid encounter (patient identifier required; gender MALE | FEMALE | UNKNOWN) and ambientOptions.sections with LOINC codes. Keep identifiers at most 36 characters. Refer to Note sections.

   Check: SukiAssistant mounts with a patient identifier, gender MALE | FEMALE | UNKNOWN, LOINC sections, and identifiers at most 36 characters.

   If it fails: Patient identifier is required, and gender must be MALE, FEMALE, or UNKNOWN. Keep identifiers at most 36 characters. Check partnerId, partnerToken, and allowlisted hosts in Web SDK prerequisites.

   import { useEffect, useMemo } from "react";
   import { SukiAuthManager } from "@suki-sdk/core";
   import { useSuki, SukiAssistant } from "@suki-sdk/react";
   
   function AmbientEncounterPage() {
   const authManager = useMemo(
   () =>
     new SukiAuthManager({
       partnerId: "YOUR_PARTNER_ID",
       partnerToken: "YOUR_PARTNER_TOKEN",
       providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
       providerOrgId: "YOUR_ORG_ID",
       environment: "staging", // Example — staging | production
       loginOnInitialize: true,
     }),
   [],
   );
   
   const { init, isInitialized } = useSuki();
   
   const encounter = useMemo(
   () => ({
     identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab", // Example only — replace with your encounter ID
     patient: {
       identifier: "905c2521-25eb-4324-9978-724636df3436", // Example only — replace with your patient ID
       name: {
         use: "official", // Example patient demographics — replace with real data
         family: "Doe",
         given: ["John"],
         suffix: [], // Required by Patient.name even when empty
       },
       birthDate: "1990-01-01", // Example only — YYYY-MM-DD
       gender: "MALE", // Example — must be "MALE" | "FEMALE" | "UNKNOWN"
     },
   }),
   [],
   );
   
   const ambientOptions = useMemo(
   () => ({
     sections: [
       { loinc: "51847-2" }, // Example section set — Assessment and Plan
       { loinc: "10164-2" }, // History of Present Illness
       { loinc: "10187-3" }, // Review of Systems — pick LOINCs that match your note
     ],
   }),
   [],
   );
   
   useEffect(() => {
   if (!isInitialized) {
     init({ authManager });
   }
   }, [init, isInitialized, authManager]);
   
   if (!isInitialized) {
   return <p>Initializing Suki Web SDK...</p>;
   }
   
   return (
   <SukiAssistant encounter={encounter} ambientOptions={ambientOptions} />
   );
   }
   

Full code example

React

// Web SDK Ambient session tutorial (React)
// Copy this file into a React app, replace YOUR_* placeholders, then render <App />.
// Flow: SukiProvider → SukiAuthManager → init → SukiAssistant (encounter + LOINC sections)

import { useEffect, useMemo } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { SukiProvider, useSuki, SukiAssistant } from "@suki-sdk/react";

// 1) Wrap once at the root. Call init() in a child under SukiProvider, not on the provider itself.
function App() {
  return (
    <SukiProvider>
      <AmbientEncounterPage />
    </SukiProvider>
  );
}

function AmbientEncounterPage() {
  // 2) One long-lived auth manager. Recreating it every render breaks login state.
  const authManager = useMemo(
    () =>
      new SukiAuthManager({
        partnerId: "YOUR_PARTNER_ID", // Required: from partner onboarding
        partnerToken: "YOUR_PARTNER_TOKEN", // Required: keep off public clients in production
        providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
        providerOrgId: "YOUR_ORG_ID", // Required — replace with your org ID
        environment: "staging", // Example — use "production" only when ready
        loginOnInitialize: true, // Sign in as soon as the manager is created
      }),
    [],
  );

  const { init, isInitialized } = useSuki();

  // 3) Encounter + patient context. Identifiers must be at most 36 characters.
  const encounter = useMemo(
    () => ({
      identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab", // Example only — replace with your encounter ID (max 36 chars)
      patient: {
        identifier: "905c2521-25eb-4324-9978-724636df3436", // Example only — replace with your patient ID (max 36 chars)
        name: {
          use: "official", // Example name fields — replace with real patient name data
          family: "Doe",
          given: ["John"],
          suffix: [], // Required by Patient.name even when empty
        },
        birthDate: "1990-01-01", // Example only — YYYY-MM-DD
        gender: "MALE", // Example — must be "MALE" | "FEMALE" | "UNKNOWN"
      },
    }),
    [],
  );

  // 4) note sections (LOINC). Required for ambient note generation.
  //    See note sections: Assessment and Plan is 51847-2 (not 51848-0 Assessment alone).
  const ambientOptions = useMemo(
    () => ({
      sections: [
        { loinc: "51847-2" }, // Example section set — Assessment and Plan
        { loinc: "10164-2" }, // History of Present Illness
        { loinc: "10187-3" }, // Review of Systems — pick LOINCs that match your note
      ],
    }),
    [],
  );

  // 5) Initialize the SDK once when the provider tree is ready.
  useEffect(() => {
    if (!isInitialized) {
      init({ authManager });
    }
  }, [init, isInitialized, authManager]);

  // 6) Optional: receive sectioned note content when the clinician submits.
  const handleNoteSubmit = (data) => {
    console.log("Note submitted:", data.noteId, data.encounterId);
    data.contents.forEach((section) => {
      console.log(`${section.title}: ${section.content}`);
    });
  };

  if (!isInitialized) {
    return <p>Initializing Suki Web SDK...</p>;
  }

  // 7) Mount the hosted Ambient UI for this encounter.
  return (
    <SukiAssistant
      encounter={encounter}
      ambientOptions={ambientOptions}
      onNoteSubmit={handleNoteSubmit}
    />
  );
}

export default App;

Troubleshooting

UI Never Opens

Confirm init({ authManager }) runs once under SukiProvider when isInitialized is false.

Auth or Allowlist Failures

Check partnerId / partnerToken and allowlisted hosts in Web SDK prerequisites.

Invalid Encounter

Patient identifier is required; gender must be MALE, FEMALE, or UNKNOWN; keep identifiers at most 36 characters.

Summary

In this tutorial, you:

• Wrapped the app with SukiProvider.
• Authenticated with SukiAuthManager and called init.
• Mounted SukiAssistant with encounter context and LOINC sections.

Prefer staging credentials until your partner configuration is production-ready.

Other tutorials

Continue with another end-to-end tutorial.