iOS使用指南

环境要求

• Xcode 16.0 及以上版本，推荐使用最新正式版本

• CocoaPods 1.9.3 及以上版本

• 准备 iOS 10.0 及以上版本的真机

集成SDK

target '你的Target' do

  # 依赖实时音视频能力，引入AliVCSDK_ARTC或AliVCSDK_Standard或AliVCSDK_InteractiveLive
  pod 'AliVCSDK_ARTC', '~> x.x.x'
  # 引入AICallKit SDK
  pod 'ARTCAICallKit', '~> 2.1.0'
  
  ...

end

工程配置

• 添加麦克风与摄像头权限，打开工程info.Plist，添加NSMicrophoneUsageDescription和NSCameraUsageDescription权限。

• 打开工程设置，在Signing & Capabilities中开启Background Modes，强烈推荐开启后台模式，否则在进入后台后无法继续通话，这时候在您的APP中需要调用结束通话接口。

SDK使用示例

// 引入SDK
import ARTCAICallKit

// 创建engine实例
var engine: ARTCAICallEngineInterface = {
    return ARTCAICallEngineFactory.createEngine()
}()

// 设置回调
self.engine.delegate = self

// 启动智能体后，开始通话
let agentInfo = ARTCAICallAgentInfo(agentType: workflow_type, channelId: channel_id, uid: ai_agent_user_id, instanceId: agent_instance_id)
self.engine.call(userId: self.userId, token: rtc_auth_token, agentInfo: agentInfo) { [weak self] error in
    if let error = error {
        // 处理错误
    }
    else {
        // 成功通话
    }
}

// 结束通话
self.engine.handup()

// 其他功能调用示例，请参考API说明

// 回调处理（仅示例不分核心的回调操作）
public func onErrorOccurs(code: ARTCAICallErrorCode) {
    // 发生了错误
    self.engine.handup()
}

public func onCallBegin() {
    // 通话开始
}

public func onCallEnd() {
    // 通话结束
}

public func onAgentStateChanged(state: ARTCAICallAgentState) {
    // 智能体状态改变
}

public func onUserSubtitleNotify(text: String, isSentenceEnd: Bool, sentenceId: Int) {
    // 用户提问被智能体识别结果的通知
}

public func onVoiceAgentSubtitleNotify(text: String, isSentenceEnd: Bool, userAsrSentenceId: Int) {
    // 智能体回答结果通知
}

public func onVoiceIdChanged(voiceId: String) {
    // 当前通话的音色发生了改变
}

public func onVoiceInterrupted(enable: Bool) {
    // 当前通话的语音打断是否启用
}

API说明

API概览

ARTCAICallEngineInterface详情

userId

获取当前通话的UserId

var userId: String? {get}

isOnCall

是否通话中, 从接通后到挂断或出错前为true，其他为false

var isOnCall: Bool { get }

agentInfo

获取当前智能体信息，包括：类型、频道Id、智能体在频道中的uid、智能体运行实例ID

var agentInfo: ARTCAICallAgentInfo? { get }

agentState

获取当前智能体状态，包括：聆听中\思考中\讲话中

var agentState: ARTCAICallAgentState { get }

delegate

设置和获取回调事件

weak var delegate: ARTCAICallEngineDelegate? { get set }

call

开始通话

func call(userId: String, token: String, agentInfo: ARTCAICallAgentInfo, completed:((_ error: NSError?) -> Void)?)

参数详情：

handup

退出通话

 func handup(_ stopAIAgent: Bool)

参数详情：

setAgentViewConfig

设置智能体渲染视图配置，当智能体有画面渲染时需要设置（当前仅针对数字人有效）

func setAgentViewConfig(viewConfig: ARTCAICallViewConfig?)

参数详情：

interruptSpeaking

打断智能体讲话

func interruptSpeaking() -> Bool

enableVoiceInterrupt

开启/关闭智能打断

func enableVoiceInterrupt(enable: Bool) -> Bool

参数详情：

switchVoiceId

切换音色

func switchVoiceId(voiceId: String) -> Bool

参数详情：

enableSpeaker

开启/关闭扬声器

func enableSpeaker(enable: Bool) -> Bool

参数详情：

enablePushToTalk

开启/关闭对讲机模式，对讲机模式下，只有在finishPushToTalk被调用后，智能体才会播报结果

func enablePushToTalk(enable: Bool) -> Bool

参数详情：

startPushToTalk

对讲机模式下，开始讲话

func startPushToTalk() -> Bool

finishPushToTalk

对讲机模式下，结束讲话

func finishPushToTalk() -> Bool

cancelPushToTalk

对讲机模式下，取消这次讲话

func cancelPushToTalk() -> Bool

muteMicrophone

静音/取消禁音麦克风

func muteMicrophone(mute: Bool) -> Bool

参数详情：

visionConfig

视觉配置，包括分辨率、帧率等，参考ARTCAICallVisionConfig的定义。使用视觉智能体时需要设置，且在通话前设置才能生效。

var visionConfig: ARTCAICallVisionConfig { set get }

muteLocalCamera

关闭/取消关闭摄像头。

func muteLocalCamera(mute: Bool) -> Bool

参数详情：

switchCamera

切换前后摄像头

func switchCamera() -> Bool

parseShareAgentCall

解析一个分享的智能体信息，解析成功则返回一个ARTCAICallAgentShareConfig类型的实例，可以通过该实例启动一个分享出来的智能体通话

func parseShareAgentCall(shareInfo: String) -> ARTCAICallAgentShareConfig?

参数详情：

generateShareAgentCall

启动一个分享的智能体通话

func generateShareAgentCall(shareConfig: ARTCAICallAgentShareConfig, userId: String, completed: ((_ rsp: ARTCAICallAgentInfo?, _ token: String?, _ error: NSError?, _ reqId: String) -> Void)?)

参数详情：

getRTCInstance

获取RTC引擎

func getRTCInstance() -> AnyObject?

sendTextToAgent

给智能体发送文本消息

func sendTextToAgent(req: ARTCAICallSendTextToAgentRequest) -> Bool

参数详情：

sendCustomMessageToServer

给Server发送自定义消息，需要在接通后调用

func sendCustomMessageToServer(msg: String) -> Bool

参数详情：

updateLlmSystemPrompt

更新LLM的系统提示词，需要在接通后调用。

func updateLlmSystemPrompt(prompt: String) -> Bool

参数详情：

startVisionCustomCapture

视觉理解智能体，开始启动自定义截帧，启动后，无法通过语音与智能体通话，需要在接通后调用

func startVisionCustomCapture(req: ARTCAICallVisionCustomCaptureRequest) -> Bool

参数详情：

stopVisionCustomCapture

视觉理解智能体，结束自定义截帧，需要在接通后调用

func stopVisionCustomCapture() -> Bool

destroy

释放资源

func destroy()

ARTCAICallEngineDelegate详情

onErrorOccurs

当前通话时发生了错误

@objc optional func onErrorOccurs(code: ARTCAICallErrorCode)

参数详情：

onCallBegin

通话开始

@objc optional func onCallBegin()

onCallEnd

通话结束

@objc optional func onCallEnd()

onAgentVideoAvailable

智能体视频是否可用

@objc optional func onAgentVideoAvailable(available: Bool)

参数详情：

onAgentAudioAvailable

智能体音频是否可用

@objc optional func onAgentAudioAvailable(available: Bool)

参数详情：

onPushToTalk

当前通话的对讲机模式是否启用

@objc optional func onPushToTalk(enable: Bool)

参数详情：

onAgentWillLeave

当前智能体即将离开（结束当前通话）

@objc optional func onAgentWillLeave(reason: Int32, message: String)

参数详情：

onReceivedAgentCustomMessage

收到当前智能体发过来的自定义消息

@objc optional func onReceivedAgentCustomMessage(data: [String: Any]?)

参数详情：

onAgentStateChanged

智能体状态改变

@objc optional func onAgentStateChanged(state: ARTCAICallAgentState)

参数详情：

onNetworkStatusChanged

网络状态改变

@objc optional func onNetworkStatusChanged(uid: String, quality: ARTCAICallNetworkQuality)

参数详情：

onVoiceVolumeChanged

音量变化通知

@objc optional func onVoiceVolumeChanged(uid: String, volume: Int32)

参数详情：

onUserSubtitleNotify

用户提问被智能体识别结果的通知

@objc optional func onUserSubtitleNotify(text: String, isSentenceEnd: Bool, sentenceId: Int)

参数详情：

onVoiceAgentSubtitleNotify

智能体回答结果通知

@objc optional func onVoiceAgentSubtitleNotify(text: String, isSentenceEnd: Bool, userAsrSentenceId: Int)

参数详情：

onVoiceIdChanged

当前通话的音色发生了改变

@objc optional func onVoiceIdChanged(voiceId: String)

参数详情：

onVoiceInterrupted

当前通话的语音打断是否启用

@objc optional func onVoiceInterrupted(enable: Bool)

参数详情：

onSpeakingInterrupted

智能体当前讲话被打断

@objc optional func onSpeakingInterrupted(reason: ARTCAICallSpeakingInterruptedReason)

参数详情：

onVisionCustomCapture

当前视觉理解通话是否启用了自定义截帧模式

@objc optional func onVisionCustomCapture(enable: Bool)

参数详情：

onAgentAvatarFirstFrameDrawn

智能体数字人首帧渲染

@objc optional func onAgentAvatarFirstFrameDrawn()

onHumanTakeoverWillStart

当真人即将接管当前智能体

@objc optional func onHumanTakeoverWillStart(takeoverUid: String, takeoverMode: Int)

参数详情：

onHumanTakeoverConnected

当真人接管已经接通

@objc optional func onHumanTakeoverConnected(takeoverUid: String)

参数详情：

onAgentEmotionNotify

智能体情绪结果通知

@objc optional func onAgentEmotionNotify(emotion: String, userAsrSentenceId: Int)

参数详情：

ARTCAICallEngineFactory详情

createEngine

创建默认的引擎实例

public static func createEngine() -> ARTCAICallEngineInterface