The Ambient Session feature in the Suki Mobile SDK allows you to manage the lifecycle of clinical note-taking sessions, including session creation, recording controls, status checks, content retrieval, and event handling.

​
1. Create a Session

Before recording, create a session with patient and section information: 
do {
    let sessionContext: [String: Any] = [
        SukiAmbientConstant.kPatientInfo: [
            SukiAmbientConstant.kName: "Saran Goda",
            SukiAmbientConstant.kBirthdate: Date(), // yyyy-mm-dd format
            SukiAmbientConstant.kGender: "MALE"
        ],
        SukiAmbientConstant.kSections: [
            ["title": "History", "description": "History"],
            ["title": "Review of systems", "description": "Review of systems"]
        ],
        SukiAmbientConstant.kSessionId: UUID().uuidString.lowercased()
    ]
    sessionId = try SukiAmbientCore.shared.createSession(withSessionInfo: sessionContext, onCompletion: { _ in })
} catch {
    print(error)
}
Notes:
  • Include patient name, birthdate, and gender.
  • Specify sections for which you want content generated (defaults are provided if omitted).
  • Optionally, provide a session ID or let the SDK generate one.
  • Handle errors using SukiAmbientCoreError.

​
2. Recording Controls

Start Recording 
do {
    try SukiAmbientCore.shared.start()
} catch {
    print(error)
}
Pause Recording 
do {
    try SukiAmbientCore.shared.pause()
} catch {
    print(error)
}
Resume Recording 
do {
    try SukiAmbientCore.shared.resume()
} catch {
    print(error)
}
End Recording 
do {
    try SukiAmbientCore.shared.end()
} catch {
    print(error)
}
Cancel Session 
do {
    try SukiAmbientCore.shared.cancel()
} catch {
    print(error)
}
  • Always ensure the SDK is initialized and a session is created before calling these methods.
  • Handle all errors using SukiAmbientCoreError.
  • iOS does not allow starting a recording in the background; handle appIsNotActive errors with user notifications if needed.

​
3. Session Status & Content Retrieval

Get Suggestion Generation Status 
SukiAmbientCore.shared.status(for: recordingId) { result in
    switch result {
    case .success(let status):
        print("status \(status)")
    case .failure(let error):
        print("error \(error)")
    }
}
Get Generated Suggestions 
SukiAmbientCore.shared.content(for: recordingId) { result in
    switch result {
    case .success(let suggestions):
        print("suggestions \(suggestions)")
    case .failure(let error):
        print("error \(error)")
    }
}
Get Audio Transcript 
SukiAmbientCoreManager.shared.transcript(for: recordingId) { result in
    switch result {
    case .success(let response):
        let transcriptText = (response.finalTranscript ?? []).compactMap { $0.transcript }.joined()
        print(transcriptText)
    case .failure(let error):
        print(error)
    }
}
  • All methods are asynchronous and require a valid recording ID.
  • The completion block returns either the result or an error.

​
4. Clearing Sessions

Clear All Sessions 
do {
    try SukiAmbientCore.shared.clear()
} catch {
    print(error)
}
  • Use during user logout to clear all sessions.
  • Do not call during an active session; this will throw an error.

​
5. Session Events & Delegates

Implement the delegate to listen for session events: 
extension AppDelegate: SukiAmbientSessionDelegate {
    func sukiAmbient(sessionEvent event: SukiAmbientCore.SessionEvent, for recordingId: SukiAmbientCore.RecordingId) {
        // Handle session events here
    }
}
Session Events enum: 
public enum SessionEvent {
    case started
    case resumed
    case paused
    case ended
    case cancelled
    case suggestionGenerationInProgress
    case suggestionsGenerated
    case suggestionsGenerationFailed
    case audioInterruptionStarted
    case audioInterruptionEnded
    case convertedToOfflineSession
    case pendingOfflineUpload
    case preparingOfflineUpload
    case uploadingAudio
    case audioUploadFailed
    case audioUploadAllRetryFailed
    case audioUploaded
    case processingUpload
    case processingUploadFailed
}

​
Best Practices

  • Always check SDK initialization and session state before calling methods.
  • Handle all errors and provide user feedback, especially for background/foreground transitions.
  • Use local notifications for important background errors.
  • Store the unique session/recording ID for future operations.

​
Best Practices & Error Handling

  • Always ensure the SDK is initialized and a session is created before calling recording methods.
  • Handle SukiAmbientCoreError in all operations to provide robust error feedback.
  • For background recording, be aware of iOS limitations: recording cannot be started in the background, and background execution time is limited.
  • Use local notifications to inform users if errors occur while the app is backgrounded.
  • Store the unique recording/session ID for future operations such as status changes or retrieving content.