Skip to main content

​
Overview

This example shows how to build a component that handles authentication, session creation, and recording in one place. It uses three hooks: useAuth, useAmbient, and useAmbientSession. The flow runs in order: sign in first, then create a session, then record.

​
Code example

React
import { useState, useEffect } from 'react';
import { useAuth, useAmbient, useAmbientSession } from '@suki-sdk/platform-react';

function SukiRecorder() {
  const [sessionId, setSessionId] = useState(null);

  // Step 1: Authenticate
  const { isLoggedIn, isPending: authPending } = useAuth({
    partnerId: 'your-partner-id', // Required, replace with your actual partner ID
    partnerToken: 'your-partner-token', // Required, replace with your actual partner token
    autoRegister: true, // Optional, set to true to automatically register the user if they don't exist
    loginOnMount: true, // Optional, set to true to sign in automatically when the component mounts
    providerName: 'Dr. John Doe', // Required for auto-registration
    providerOrgId: 'org-123', // Required for auto-registration
    providerSpecialty: 'Cardiology' // Required for auto-registration
  });

  // Step 2: Create session
  const {
    ambientSessionId,
    session: { create, isSuccess: sessionCreated }
  } = useAmbient();

  useEffect(() => {
    if (isLoggedIn && !sessionCreated) {
      create();
    }
  }, [isLoggedIn, sessionCreated, create]);

  useEffect(() => {
    if (ambientSessionId) {
      setSessionId(ambientSessionId);
    }
  }, [ambientSessionId]);

  // Step 3: Manage recording
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType, // New in v0.2.2
  } = useAmbientSession({
    ambientSessionId: sessionId
  });

  if (authPending) {
    return <div>Authenticating...</div>;
  }

  if (!isLoggedIn) {
    return <div>Please sign in</div>;
  }

  if (!sessionId) {
    return <div>Creating session...</div>;
  }

  return (
    <div>
      <h2>Recording Status: {sessionStatus}</h2>
      {sessionType === 'offline' && ( // added in v0.2.2
        <p>Session will sync when online</p>
      )}
      
      {sessionStatus === 'created' && (
        <button onClick={start}>Start Recording</button>
      )}
      
      {sessionStatus === 'recording' && (
        <>
          <button onClick={pause}>Pause</button>
          <button onClick={submit}>Submit</button>
        </>
      )}
      
      {sessionStatus === 'paused' && (
        <>
          <button onClick={resume}>Resume</button>
          <button onClick={submit}>Submit</button>
        </>
      )}
    </div>
  );
}

​
Key implementation details

Authentication: The useAuth hook signs the user in. With autoRegister: true and loginOnMount: true, sign-in runs when the component mounts. If the user does not exist, the SDK registers them first. When using auto-registration, you must pass providerName, providerOrgId, and providerSpecialty. See the Authentication hook guide.
Session Creation: The useAmbient hook creates a new ambient session. Call session.create() only after the user is logged in. Wait for isSuccess to be true before using ambientSessionId. Passing undefined to useAmbientSession will cause errors. See the Create ambient session guide.
Recording: The useAmbientSession hook controls recording. Pass the ambientSessionId from step 2. The hook returns start, pause, resume, and submit methods. It also returns sessionStatus and sessionType so you can update your UI. See the Manage ambient session guide.
Always wait for isSuccess to be true before using ambientSessionId. Passing an undefined session ID to useAmbientSession will cause errors.

​
Next steps

Refer to the Manage ambient session guide to learn how to add session context and improve note quality.
Last modified on March 23, 2026