# iOS 原生 RTC SDK 函数参考

适用 同批交付 Swift SDK/XCFramework。`AkNativeRtcClient` 在主 actor 上工作，负责设备会话、音视频轨道、WHIP/WHEP、信令和恢复；UIKit/SwiftUI 宿主负责按钮、权限提示、渲染视图、音频路由与 ReplayKit 扩展。先按[iOS 接入步骤](ios.md)安装依赖、配置签名和系统采集权限。

```swift
let rtc = AkNativeRtcClient(localRenderer: previewRenderer, delegate: self)
rtc.setInitialMediaEnabled(microphone: false, camera: false)
rtc.joinWithAccessTicket(baseURL: serverURL, roomID: roomID,
                             accessTicket: oneUseTicket, passcode: "")
```

`serverURL` 是 iPhone 可验证证书的 HTTPS 地址，不能使用 Mac 的 `127.0.0.1`。票据来自业务后端，只能消费一次。`@MainActor` 方法从对应 actor 调用；异步抛错和 delegate 错误要保留 HTTP 状态。

## 会话、主持与录制

| 函数 | 入参 | 结果 | 特殊情况 |
|---|---|---|---|
| `AkNativeRtcClient(localRenderer:delegate:)` | 本机 `RTCVideoRenderer`、`AkNativeRtcClientDelegate` | 客户端对象 | SDK监听前后台；一场活动会议只保留一份客户端。 |
| `joinWithAccessTicket(baseURL:roomID:accessTicket:passcode:)` | 服务地址、会议号、一次性票据、口令（无口令用空串） | delegate 的 `didJoin` 或 `didFailHTTP/didFail` | 等候室未准入时不能发布；票据不可重放。 |
| `createMeeting(settings:creator:)` | 设置字典、业务后端 `async throws` 建会回调 | 含 `roomId/accessTicket` 的字典 | 回调应做业务认证、幂等重试；管理凭据不交给 App。 |
| `listMembers()`、`participantForPublication(_:)` | 后者传发布 ID | 成员列表事件 / 成员 ID 或 `nil` | 成员和设备会因重连变化；画面以发布 ID 区分。 |
| `performRoomAction(_:payload:)` | [白名单动作](room-actions.md)及字段 | `async throws -> Any` | 服务端再次校验角色、设备与权限；403 不能靠重试绕过。 |
| `startContinuousRecording()`、`stopContinuousRecording(recordingId:)`、`getContinuousRecording()` | 停录需本次任务 ID | `async throws` 状态；无任务时为空 | 仅当前主持人启停；`didChangeContinuousRecording` 报告活动状态。 |
| `leave()`、`close()` | 无 | 设备离会 / 对象结束 | 页面销毁和路由切换走一致清理；被踢后换新业务授权。 |
| `listDemoRooms(baseURL:)`、`createDemoMeeting(...)`、`issueDemoAccessTicket(...)` | 独立测试环境参数 | Demo 房间/票据 | 不作为正式业务用户系统。 |

`getContinuousRecording()` 查询的是**当前活动任务**，不是历史录像。会后查询和资源 URL 使用独立[档案 SDK](archive-api.md)及 `view/play/download` 票据。主持移交后旧主持人立即失去主持专属录制权限。

## 本机媒体、摄像头和共享

| 函数 | 入参 | 结果 | 特殊情况 |
|---|---|---|---|
| `setInitialMediaEnabled(microphone:camera:)` | 首次入会意图 | 初始化麦克风/相机状态 | 系统授权、会议能力和主持策略仍会限制实际发布。 |
| `setMicrophoneEnabled(_:)`、`setCameraEnabled(_:)` | 布尔值 | 经 `didChangeLocalMedia` 反馈 | 不能以按钮点击成功替代远端实际收帧/声音。 |
| `listCameras()`、`switchCamera(to:)` | 可选摄像头 ID | `AkRtcCameraDevice` 列表 / `didSwitchCamera` | 位置用 `AVCaptureDevice.Position`；设备列表可能在授权或连接变化后更新。 |
| `setRemoteAudioVolume(publicationID:volume:)` | 发布 ID、0～1 音量 | 本机播放改变 | 不改变对方麦克风，也不影响录制原轨。 |
| `setForeground(_:)` | 前后台布尔值 | 采集生命周期变化 | SDK已监听系统通知；自定义场景转场时可显式同步，避免相机资源被系统占用。 |
| `getSupportedVideoModes()`、`getEndpointInfo()` | 无 | 视频模式与终端参数字典 | 能力值不是当前实际帧率；上报不含硬件唯一标识。 |
| `makeCameraPictureInPicture(sourceView:)` | 摄像头画面的 UIView | `AkRtcCameraPictureInPicture` 或抛错 | 画中画是本机显示能力，不会新增发布或改录像。 |
| `prepareBroadcast(appGroup:)`、`broadcastIsActive()`、`stopBroadcastShare()` | App Group 标识 / 无参 | ReplayKit 准备、状态、停止 | 需要已签名的广播扩展和共享 App Group；系统可随时结束共享。 |

屏幕共享与摄像头是独立流。ReplayKit 扩展负责系统采集，主 App 只传受信任的短时会话上下文；不要把票据写进共享文件日志或交给其他 App。

## 聊天、白板、附件与事件

| 函数 | 入参 | 结果 | 特殊情况 |
|---|---|---|---|
| `sendChatMessage(_:targetParticipantID:)` | 文本、可选私发成员 ID | `didReceiveChatMessage`/错误 | 私发消息不进入公共回放。 |
| `uploadAttachment(data:fileName:contentType:caption:targetParticipantID:)`、`uploadAttachment(fileURL:caption:targetParticipantID:)` | 字节或本地文件 URL、类型/说明/目标 | `didUploadAttachment` 或错误 | 最终提交会复核当前设备、会议与私发权限；大文件优先文件 URL。 |
| `uploadWhiteboardImage(fileURL:)` | 本机图片文件 URL | `async throws -> AkRtcChatAttachment` | 上传图片素材后还需提交白板对象；收回书写权会阻止最终使用。 |
| `downloadAttachment(_:)`、`downloadAttachmentFile(_:)`、`releaseAttachmentFile(_:)` | 获准附件 / 本机临时文件 URL | `Data`、临时文件 URL / 释放 | 大文件用文件接口；用完释放 SDK 临时文件。 |
| `attachmentPreview(_:maxDimension:)` | 图片附件、像素边长上限 | 可预览 `UIImage?` | 非图片或解码失败时可能为空；PDF/视频由宿主选择合适预览器。 |
| `sendHandRaised(_:)`、`sendReaction(_:)` | 举手布尔值、反应名 | 会议事件 | 不改变成员发布权限。 |

delegate 关键回调：`didReceiveRemoteVideo/didRemoveRemoteVideo`、`didReceiveRemoteAudio/didRemoveRemoteAudio` 管每路视图；`didChangeLocalMedia` 与 `didChangeMediaPermission` 管按钮；`didChangeCapabilities` 管主持 UI；`didReceiveWhiteboardEvent/didReceiveChatMessage` 管协作；`didChangeContinuousRecording` 管录制提示；`didFailHTTP` 保留状态码；`nativeRtcClientDidLeave` 触发最终清理。旧会话事件不能复活新会话的权限或画面。