Session Management

Managing Ambient sessions, lifecycle, and data handling in the Mobile SDK

How Do I Create a New Session?

Call createSession(with:onCompletion:) after you initialize the SDK. Pass optional session info such as SukiAmbientConstant.kEmrEncounterId for interoperable notes, SukiAmbientConstant.kSessionId (Ambient API encounter_id) for re-ambient workflows, and SukiAmbientConstant.kIsMultilingual when the visit is not English only.

Patient demographics are not part of createSession. After create succeeds, pass patient, provider, visit, and related context with setSessionContext(with:).

Refer to Create ambient session and Provide clinical context.

What Patient Information Is Required for Session Creation?

None. createSession does not require patient name, birthdate, or gender.

After the session is created, you can pass optional patient demographics in setSessionContext under SukiAmbientConstant.kPatientInfo:

• Birthdate (SukiAmbientConstant.kBirthdate): date of birth.
• Gender (SukiAmbientConstant.kGender): "MALE" or "FEMALE".
• Patient id (SukiAmbientConstant.kPatientId): partner or EMR patient identifier. Available from Mobile SDK v2.7.0.
• Patient name (SukiAmbientConstant.kPatientName): structured name with optional "family", "given", "suffix", and "use". Available from Mobile SDK v2.7.0.

All of these fields are optional. Including them helps personalize note generation. Refer to Provide clinical context.

Can I Update Session Information After Creation?

Yes. Call setSessionContext(with:) after createSession succeeds to add or update patient info, provider context, visit context, EMR info, note sections, diagnosis info, and medication orders. You can call it more than once as data becomes available in your app.

Refer to Provide clinical context.

Does the Mobile SDK Support Problem-Based Charting (PBC)?

Yes. Pass existing patient diagnoses with SukiAmbientConstant.kDiagnosisInfo in setSessionContext, configure LOINC sections for the note, and retrieve structured diagnoses after the session with getStructuredData(for:). Behavior matches the Ambient APIs for reconciliation and output. Refer to Problem-Based Charting, Create session, and Session status and content retrieval.

What Are the Different Session States?

Sessions can be in the following states:

• NotCreated: No session has been initialized.
• Recording: Session is actively recording audio.
• Paused: Recording is temporarily paused.
• Ended: Session completed, content generation in progress.
• Canceled: Session was canceled, no content will be generated.

Check the current state using SukiAmbientCoreManager.shared.sessionState.

Can I Pause and Resume a Recording Session?

Yes, you can pause and resume sessions:

The SDK provides pause and resume methods to temporarily stop and restart recording while keeping the session active.

Note that you can only pause an active recording and only resume a paused session.

What's the Difference Between Ending and Canceling a Session?

• End: Stops recording and begins AI content generation. Use this for completed sessions.
• Cancel: Stops recording and discards all data. No content will be generated. This action cannot be undone.

End stops recording and begins AI content generation for completed sessions, while Cancel stops recording and discards all data with no content generation.

Can I Have Multiple Active Sessions?

The current SDK version supports one active session at a time. You must end or cancel the current session before creating a new one. Locally, create can return sessionInProgress. Across devices for the same EMR encounter, create can return remoteSessionConflict(blockingSessionId:). Refer to Ambient interoperability.

How Do I Share a Note with Web SDK or Ambient APIs?

Pass SukiAmbientConstant.kEmrEncounterId on createSession to make the note interoperable. For re-ambient workflows, pass SukiAmbientConstant.kSessionId (Ambient API encounter_id) and reuse the same value for every session on that note. Store sessionId and compositionId when present. Refer to Ambient interoperability and Interoperable identifiers.

Are sessionId and recordingId the Same?

Yes. In the Mobile SDK, sessionId and recordingId are the same value. Use sessionId from the createSession response for recording controls and session-scoped APIs. It maps to Ambient API ambient_session_id.

How Do I Handle Session Errors?

All session methods can throw SukiAmbientCoreError. Always use do-catch blocks:

All session methods can throw SukiAmbientCoreError. Use do-catch blocks to handle errors like session not initialized or attempting to record in the background. Create can also return SukiStatus for FAILED_PRECONDITION and INVALID_ARGUMENT without offline fallback.

What Happens If I Try to Start Recording in the Background?

iOS doesn’t allow apps to start recording while in the background. The SDK will throw an appIsNotActive error. You should:

1. Handle this error gracefully.
2. Notify the user to bring the app to the foreground.
3. Retry the operation once the app is active.

How Do I Know When Content Generation Is Complete?

Use the session delegate to receive real-time updates:

Use the session delegate to receive real-time updates about content generation completion and handle events like suggestions generated or generation failures.