端到端教程·iOS 篇

import Foundation

enum AppConfig {
    /// 你自己后端的地址,换成真实域名
    static let backendBaseURL = URL(string: "https://your-backend.example.com")!
    /// 你应用自己的登录态(示例用静态值,正式应用接入你自己的账号体系)
    static var sessionToken = ""
    /// 你系统里的用户标识,与后端篇 /token、/recordings/complete 的 user_id 一致
    static var userId = ""
    /// 后端签发的用户令牌,第 2 步配置 SDK 时顺手保存,第 5 步直传文件也要用
    static var userAccessToken = ""
}

/// 你后端 POST /token 的响应,字段与后端篇保持一致
struct TokenResponse: Codable {
    let accessToken: String
    let tokenType: String
    let expiresIn: Int
}

final class TokenClient {
    private let session = URLSession(configuration: .default)

    /// 向你自己的后端换取用户令牌
    func fetchUserToken() async throws -> TokenResponse {
        var request = URLRequest(url: AppConfig.backendBaseURL.appendingPathComponent("token"))
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        // 用你应用自己的登录态做鉴权,后端据此识别是哪位用户
        request.setValue("Bearer " + AppConfig.sessionToken, forHTTPHeaderField: "Authorization")
        request.httpBody = try JSONEncoder().encode(["user_id": AppConfig.userId])

        let (data, response) = try await session.data(for: request)
        guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
            throw URLError(.badServerResponse)
        }
        let decoder = JSONDecoder()
        decoder.keyDecodingStrategy = .convertFromSnakeCase
        return try decoder.decode(TokenResponse.self, from: data)
    }
}

{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86400
}

import SwiftUI
import IKhoEmbedded

@main
struct S1TutorialApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

struct ContentView: View {
    @StateObject private var store = DeviceStore()
    @State private var configured = false
    @State private var failed = false

    var body: some View {
        NavigationStack {
            if failed {
                VStack(spacing: 12) {
                    Text("初始化失败,请检查网络后重试")
                    Button("重试") {
                        failed = false
                        Task { await configureSDK() }
                    }
                }
            } else if !configured {
                ProgressView("正在准备")
                    .task { await configureSDK() }
            } else if store.phase != .ready {
                PairingView(store: store)          // 见「第 3 步:扫描并绑定 S1」
            } else {
                RecordingListView(store: store)    // 见「第 4 步:同步设备上的录音」
            }
        }
    }

    private func configureSDK() async {
        do {
            let token = try await TokenClient().fetchUserToken()
            AppConfig.userAccessToken = token.accessToken   // 第 5 步直传文件也要用
            IKhoEmbedded.configure(userToken: token.accessToken)
            configured = true
        } catch {
            failed = true
        }
    }
}

let token = try await TokenClient().fetchUserToken()
IKhoEmbedded.setUserToken(token.accessToken)

import Foundation
import IKhoEmbedded

final class DeviceStore: ObservableObject {

    enum Phase: Equatable {
        case idle       // 未绑定
        case scanning   // 扫描中
        case binding    // 绑定中
        case ready      // 已绑定,可同步
    }

    @Published var phase: Phase = .idle
    @Published var discovered: [IKhoDevice] = []
    @Published var batteryLevel = 0
    @Published var isCharging = false
    @Published var recordings: [IKhoRecording] = []
    @Published var syncProgress: [String: Int] = [:]   // recordingId → 0–100
    @Published var localFiles: [String: String] = [:]  // recordingId → 本地文件路径
    @Published var lastError: String?

    init() {
        IKhoDeviceManager.shared.delegate = self
    }

    func startScan() {
        phase = .scanning
        discovered = []
        IKhoDeviceManager.shared.scanDevices()
    }

    func bind(_ device: IKhoDevice) {
        phase = .binding
        IKhoDeviceManager.shared.stopScan()
        IKhoDeviceManager.shared.bind(device: device)
    }

    func refreshRecordings() {
        IKhoDeviceManager.shared.fetchRecordings()
    }

    func sync(_ recording: IKhoRecording) {
        syncProgress[recording.id] = 0
        IKhoDeviceManager.shared.exportAudio(recordingId: recording.id, format: .m4a)
    }
}

// 连接与状态回调
extension DeviceStore: IKhoDeviceDelegate {

    func deviceScanResult(_ devices: [IKhoDevice]) {
        DispatchQueue.main.async {
            self.discovered = devices
        }
    }

    func deviceBindChanged(_ result: IKhoBindResult) {
        DispatchQueue.main.async {
            if result.bound {
                self.phase = .ready
                IKhoDeviceManager.shared.fetchRecordings()
            } else {
                self.phase = .idle
            }
        }
    }

    // 唯一必须实现的回调:握手完成后返回设备总体状态
    func deviceStateChanged(_ state: IKhoDeviceState) {
        DispatchQueue.main.async {
            self.batteryLevel = state.batteryLevel
            self.isCharging = state.isCharging
        }
    }

    func deviceBatteryChanged(level: Int, isCharging: Bool) {
        DispatchQueue.main.async {
            self.batteryLevel = level
            self.isCharging = isCharging
        }
    }

    func didEncounterError(_ error: IKhoError) {
        DispatchQueue.main.async {
            self.lastError = error.localizedDescription
        }
    }
}

import SwiftUI
import IKhoEmbedded

struct PairingView: View {
    @ObservedObject var store: DeviceStore

    var body: some View {
        List {
            Section("附近的 S1") {
                ForEach(store.discovered, id: \.serialNumber) { device in
                    Button {
                        store.bind(device)
                    } label: {
                        HStack {
                            Text(device.serialNumber)
                            Spacer()
                            if store.phase == .binding {
                                ProgressView()
                            }
                        }
                    }
                }
                if store.discovered.isEmpty {
                    Text(store.phase == .scanning ? "正在扫描附近设备" : "点右上角「开始扫描」查找设备")
                        .foregroundStyle(.secondary)
                }
            }
        }
        .navigationTitle("绑定 S1")
        .toolbar {
            Button("开始扫描") {
                store.startScan()
            }
        }
    }
}

// 录音列表与同步回调
extension DeviceStore {

    func recordingListUpdated(_ recordings: [IKhoRecording]) {
        DispatchQueue.main.async {
            self.recordings = recordings
        }
    }

    func exportProgress(recordingId: String, progress: Int) {
        DispatchQueue.main.async {
            self.syncProgress[recordingId] = progress
        }
    }

    func exportCompleted(recordingId: String, outputPath: String) {
        DispatchQueue.main.async {
            self.syncProgress[recordingId] = nil
            self.localFiles[recordingId] = outputPath
        }
    }

    func exportFailed(recordingId: String, error: IKhoError) {
        DispatchQueue.main.async {
            self.syncProgress[recordingId] = nil
            self.lastError = "同步失败:" + error.localizedDescription
        }
    }
}

import SwiftUI
import IKhoEmbedded

struct RecordingListView: View {
    @ObservedObject var store: DeviceStore

    var body: some View {
        List(store.recordings, id: \.id) { recording in
            VStack(alignment: .leading, spacing: 6) {
                HStack {
                    Text(Self.duration(recording.durationSeconds))
                        .font(.body.monospacedDigit())
                    Spacer()
                    if let progress = store.syncProgress[recording.id] {
                        Text("\(progress)%")
                            .font(.caption)
                            .foregroundStyle(.secondary)
                    } else if store.localFiles[recording.id] != nil {
                        Text("已同步")
                            .font(.caption)
                            .foregroundStyle(.secondary)
                    } else {
                        Button("同步") {
                            store.sync(recording)
                        }
                    }
                }
                if let progress = store.syncProgress[recording.id] {
                    ProgressView(value: Double(progress), total: 100)
                }
            }
            .padding(.vertical, 4)
        }
        .navigationTitle("设备上的录音")
        .refreshable {
            store.refreshRecordings()
        }
    }

    static func duration(_ seconds: Int) -> String {
        String(format: "%02d:%02d", seconds / 60, seconds % 60)
    }
}

import Foundation

enum BackendError: Error {
    case badResponse
    case transcriptionFailed
}

/// 预签名上传计划(字段名与文件上传 API 一致,PascalCase 用显式 CodingKeys)
struct UploadPlan: Decodable {
    let fileId: String
    let uploadId: String
    let chunkSize: Int
    let parts: [Part]

    struct Part: Decodable {
        let partNumber: Int
        let presignedUrl: String
        enum CodingKeys: String, CodingKey {
            case partNumber = "PartNumber", presignedUrl = "PresignedUrl"
        }
    }
    enum CodingKeys: String, CodingKey {
        case fileId = "FileId", uploadId = "UploadId", chunkSize = "ChunkSize", parts = "Parts"
    }
}

/// 合并分片的响应
struct CompleteUploadResponse: Decodable {
    let downloadUrl: String
    enum CodingKeys: String, CodingKey { case downloadUrl = "DownloadUrl" }
}

/// 你后端 /recordings/complete 的响应,字段与后端篇一致
struct CompleteResponse: Codable {
    let transcriptionId: String
    let status: String
}

struct TranscriptSegment: Codable, Identifiable {
    let speaker: String?
    let startMs: Int
    let endMs: Int
    let text: String
    var id: Int { startMs }
}

/// 你后端逐字稿接口的响应;status 透传平台任务状态
struct TranscriptResponse: Codable {
    let status: String
    let segments: [TranscriptSegment]?
}

/// 用用户令牌把音频直传 iKho 存储:预签名 → 分片 PUT → 合并,拿到 DownloadUrl
final class IKhoFileClient {
    private let host = URL(string: "https://platform.ikho.cn/developer/api")!
    private let session = URLSession(configuration: .default)

    func upload(fileURL: URL) async throws -> String {
        let audio = try Data(contentsOf: fileURL)
        let filetype = fileURL.pathExtension.lowercased()   // m4a / mp3 / wav

        // 1. 申请预签名上传计划
        let plan: UploadPlan = try await postJSON(
            path: "/open/partner/files/upload/generate-presigned-urls",
            body: ["filesize": audio.count, "filetype": filetype]
        )

        // 2. 按 ChunkSize 切分,逐片 PUT 到预签名地址,收集 ETag
        var partList: [[String: Any]] = []
        for part in plan.parts {
            let start = (part.partNumber - 1) * plan.chunkSize
            let end = min(start + plan.chunkSize, audio.count)
            var put = URLRequest(url: URL(string: part.presignedUrl)!)
            put.httpMethod = "PUT"
            let (_, resp) = try await session.upload(for: put, from: audio[start..<end])
            guard let http = resp as? HTTPURLResponse, http.statusCode == 200,
                  let etag = http.value(forHTTPHeaderField: "ETag") else {
                throw BackendError.badResponse
            }
            partList.append(["part_number": part.partNumber, "etag": etag])
        }

        // 3. 合并分片,拿到可下载地址
        let done: CompleteUploadResponse = try await postJSON(
            path: "/open/partner/files/upload/complete-upload",
            body: ["file_id": plan.fileId, "upload_id": plan.uploadId,
                   "part_list": partList, "filetype": filetype]
        )
        return done.downloadUrl
    }

    private func postJSON<T: Decodable>(path: String, body: [String: Any]) async throws -> T {
        var request = URLRequest(url: host.appendingPathComponent(path))
        request.httpMethod = "POST"
        request.setValue("Bearer " + AppConfig.userAccessToken, forHTTPHeaderField: "Authorization")
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = try JSONSerialization.data(withJSONObject: body)
        let (data, response) = try await session.data(for: request)
        guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
            throw BackendError.badResponse
        }
        return try JSONDecoder().decode(T.self, from: data)
    }
}

final class BackendClient {
    private let session = URLSession(configuration: .default)
    private let decoder: JSONDecoder = {
        let d = JSONDecoder()
        d.keyDecodingStrategy = .convertFromSnakeCase
        return d
    }()

    /// 把 DownloadUrl 回报给你自己的后端,由后端提交转写
    func reportComplete(fileUrl: String) async throws -> CompleteResponse {
        var request = URLRequest(url: AppConfig.backendBaseURL
            .appendingPathComponent("recordings")
            .appendingPathComponent("complete"))
        request.httpMethod = "POST"
        request.setValue("Bearer " + AppConfig.sessionToken, forHTTPHeaderField: "Authorization")
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = try JSONEncoder().encode([
            "user_id": AppConfig.userId,
            "file_url": fileUrl,
        ])

        let (data, response) = try await session.data(for: request)
        guard let http = response as? HTTPURLResponse, (200...202).contains(http.statusCode) else {
            throw BackendError.badResponse
        }
        return try decoder.decode(CompleteResponse.self, from: data)
    }

    /// 轮询你后端的逐字稿接口,SUCCESS 后返回 segments
    func waitForTranscript(transcriptionId: String) async throws -> [TranscriptSegment] {
        let url = AppConfig.backendBaseURL
            .appendingPathComponent("recordings")
            .appendingPathComponent(transcriptionId)
            .appendingPathComponent("transcript")
        var request = URLRequest(url: url)
        request.setValue("Bearer " + AppConfig.sessionToken, forHTTPHeaderField: "Authorization")

        while true {
            let (data, response) = try await session.data(for: request)
            guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
                throw BackendError.badResponse
            }
            let result = try decoder.decode(TranscriptResponse.self, from: data)
            switch result.status {
            case "SUCCESS":
                return result.segments ?? []
            case "FAILURE", "REVOKED":
                throw BackendError.transcriptionFailed
            default:
                // PENDING / RECEIVED / STARTED / PROGRESS:间隔 3 秒继续轮询
                try await Task.sleep(nanoseconds: 3_000_000_000)
            }
        }
    }
}

{
  "status": "SUCCESS",
  "segments": [
    { "speaker": "发言人 1", "start_ms": 0, "end_ms": 4600, "text": "王先生您好,上次复诊后睡眠情况怎么样。" },
    { "speaker": "发言人 2", "start_ms": 4600, "end_ms": 9200, "text": "比之前好一些,不过后半夜还是容易醒。" },
    { "speaker": "发言人 1", "start_ms": 9200, "end_ms": 14100, "text": "好的,我把剂量再微调一下,两周后我们再看一次。" }
  ]
}

import SwiftUI

struct TranscriptScreen: View {
    /// 已同步到本地的音频文件路径(exportCompleted 返回的 outputPath)
    let localPath: String

    @State private var segments: [TranscriptSegment] = []
    @State private var stateText = "正在上传录音"
    @State private var failed = false

    var body: some View {
        Group {
            if failed {
                Text("转写失败,请返回重试")
                    .foregroundStyle(.secondary)
            } else if segments.isEmpty {
                ProgressView(stateText)
            } else {
                TranscriptView(segments: segments)
            }
        }
        .task { await load() }
        .navigationTitle("逐字稿")
    }

    private func load() async {
        do {
            // 1. 用用户令牌把音频直传 iKho 存储,拿到 DownloadUrl
            let downloadUrl = try await IKhoFileClient()
                .upload(fileURL: URL(fileURLWithPath: localPath))
            // 2. 回报你的后端,由后端提交转写
            let backend = BackendClient()
            let created = try await backend.reportComplete(fileUrl: downloadUrl)
            stateText = "转写中,请稍候"
            // 3. 轮询你的后端直到 SUCCESS
            segments = try await backend.waitForTranscript(transcriptionId: created.transcriptionId)
        } catch {
            failed = true
        }
    }
}

struct TranscriptView: View {
    let segments: [TranscriptSegment]

    var body: some View {
        List(segments) { segment in
            VStack(alignment: .leading, spacing: 4) {
                HStack(spacing: 8) {
                    Text(segment.speaker ?? "发言人")
                        .font(.subheadline.weight(.semibold))
                    Text(Self.timestamp(ms: segment.startMs))
                        .font(.caption.monospacedDigit())
                        .foregroundStyle(.secondary)
                }
                Text(segment.text)
                    .font(.body)
            }
            .padding(.vertical, 4)
        }
        .listStyle(.plain)
    }

    static func timestamp(ms: Int) -> String {
        let total = ms / 1000
        return String(format: "%02d:%02d", total / 60, total % 60)
    }
}

// RecordingListView 中,把「已同步」标签换成逐字稿入口
if let path = store.localFiles[recording.id] {
    NavigationLink("查看逐字稿") {
        TranscriptScreen(localPath: path)
    }
    .font(.caption)
}