Skip to main content

​
Overview

The Suki Mobile SDK provides methods to manage the entire lifecycle of an ambient session. This guide covers how to create a session and enrich it with detailed clinical context.

​
Create An Ambient Session

Before you can start a recording, you must create a session. Call the createSession(withSessionInfo:) method to initialize the session. Upon success, this method returns a sessionId that you must store to reference this session in future calls. 
do {
    // Define the initial context for the session.
    let sessionContext: [String: Any] = [
        SukiAmbientConstant.kPatientInfo: [
            SukiAmbientConstant.kName: "Saran Goda",
            SukiAmbientConstant.kBirthdate: Date(), // Use 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(),
        SukiAmbientConstant.kMultilingual: true
    ]

    // Create the session and store the returned sessionId.
    sessionId = try SukiAmbientCore.shared.createSession(withSessionInfo: sessionContext, onCompletion: { _ in
        // Handle completion if needed.
    })
} catch {
    // Handle potential SukiAmbientCoreError.
    print(error)
}

​
Session Info Parameters

The withSessionInfo dictionary can contain the following keys:
  • SukiAmbientConstant.kPatientInfo: A dictionary containing the patient’s name, birthdate, and gender.
  • SukiAmbientConstant.kSections: An array of dictionaries that define the clinical sections for note generation. If you omit this, default sections are used.
  • SukiAmbientConstant.kSessionId: An optional unique identifier for the session. If you do not provide one, the SDK generates it for you.
  • SukiAmbientConstant.kMultilingual: A boolean that enables multilingual processing for the session. The default is false (English only). This setting applies to the entire session and cannot be changed mid-session.
After creating a session, you can add more detailed information by calling the setSessionContext(with:) method. This is the recommended way to provide context like provider specialty, LOINC codes, and structured diagnosis information.
This method uses an API that supports partial updates. You can call it multiple times to update or add different pieces of context after the session has been created.
do {
    let contextDetail: [String: AnyHashable] = [
        SukiAmbientConstant.kPatientInfo: [
            SukiAmbientConstant.kBirthdate: Date(), // Use yyyy-mm-dd format
            SukiAmbientConstant.kGender: "MALE"
        ],
        SukiAmbientConstant.kProviderContext: [
            SukiAmbientConstant.kSpeciality: "FAMILY_MEDICINE"
        ],
        SukiAmbientConstant.kSections: [
            [SukiAmbientConstant.kCode: "51848-0", SukiAmbientConstant.kCodeType: "loinc"],
            [SukiAmbientConstant.kCode: "11450-4", SukiAmbientConstant.kCodeType: "loinc"]
        ],
        SukiAmbientConstant.kDiagnosisInfo: [
            [
                SukiAmbientConstant.kDiagnosisNote: "Patient presents with chest pain",
                SukiAmbientConstant.kCodes: [
                    [
                        SukiAmbientConstant.kCodeType: "ICD-10",
                        SukiAmbientConstant.kCode: "R06.02",
                        SukiAmbientConstant.kCodeDescription: "Shortness of breath"
                    ]
                ]
            ]
        ]
    ]
    
    try SukiAmbientCore.shared.setSessionContext(with: contextDetail) { result in
        // Handle the asynchronous completion result.
    }
} catch {
    print(error)
}
You can only call setSessionContext(with:) after a session has been successfully created. You must provide valid speciality strings and codes.

​
Context Detail Parameters

The with dictionary can contain the following keys:
  • SukiAmbientConstant.kPatientInfo: A dictionary for updating patient birthdate and gender.
  • SukiAmbientConstant.kProviderContext: A dictionary containing the provider’s speciality.
  • SukiAmbientConstant.kSections: An array of dictionaries for mapping sections to specific LOINC codes.
You no longer need to provide section titles. The SDK will automatically generate the appropriate clinical sections based on the LOINC codes you provide.
  • SukiAmbientConstant.kDiagnosisInfo: An array of dictionaries for passing structured diagnosis context. Each dictionary can contain:
    • kDiagnosisNote: An optional string with notes about the diagnosis.
    • kCodes: An array of one or more dictionaries for the diagnosis codes. Each code dictionary must contain:
      • kCodeType: (Required) The type of code (e.g., “ICD-10”, “IMO”, “SNOMED”).
      • kCode: (Required) The diagnosis code.
      • kCodeDescription: An optional but recommended description of the code.

​
Best Practices And Error Handling

To ensure a robust integration, follow these best practices:
  • Always ensure the SDK is initialized and a session is created before you call recording methods.
  • Handle SukiAmbientCoreError in all operations to provide robust error feedback, especially for background and foreground transitions.
  • Be aware of iOS limitations for background recording. A recording cannot be started while the app is in the background, and execution time is limited. Use local notifications to inform users if errors occur while the app is backgrounded.
  • Store the unique recording or session ID for future operations, such as handling status changes or retrieving content.

​
FAQs

The session creation can fail for several reasons:Common causes:
  • Invalid partner information
  • Network connectivity issues
  • Authentication token problems
  • Missing microphone permissions
Debugging steps: Debug session creation failures by checking the completion handler result and catching session creation errors. Verify partner information, network connectivity, and required permissions.
The session context is not being updated because the setSessionContext method is not being called. You must ensure that you are calling the setSessionContext method after the session has been created.
The session is created but the user is not able to start recording because the session is not in a valid state. You must ensure that the session is in a valid state before the user can start recording. To start recording, you must call the start method.

​
Next Steps

After you create a session, proceed to our Recording Controls guide to learn how to manage the recording lifecycle.
⌘I