原生 iOS 接入

原生 iOS SDK 用于在 App 内打开完整的访客聊天页面。接入完整聊天页时使用交付包中的 Agent99VisitorUIKit。

增值服务

原生 iOS 接入属于单独付费的项目。如需获取 iOS SDK 源码包或安排接入支持，请联系我们。

接入准备

• 支持 iOS 13 及以上版本。
• 在商户后台准备 API 密钥，并由业务服务端为已登录用户签发访客令牌。请勿将 API 密钥写入 App。
• 将交付的 iOS SDK 源码通过 Swift Package Manager 或 CocoaPods 添加到工程；需要完整聊天页时引入 Agent99VisitorUIKit。

配置访客身份

建议在用户登录完成后配置。用户 ID 由业务服务端在访客令牌中确认；客户端配置昵称、头像，以及 attributes（即 visitor.attr 扩展信息）。下面示例中的 fetchVisitorToken() 应请求您的业务服务端，由服务端返回当前用户的访客令牌；令牌的签发方式请参阅用户基础信息对接。

import Agent99VisitorUIKit

let config = try VisitorConfig(
    baseUrl: "https://live.99kf.com",
    language: "zh-CN"
)

Visitor.configure(
    config: config,
    auth: .tokenProvider {
        try await appAPI.fetchVisitorToken()
    },
    visitor: VisitorProfile(
        nickname: "张三",
        avatar: "https://www.99kf.com/avatar/12.jpg",
        attributes: [
            VisitorAttribute(key: "phone", label: "电话", value: .string("13800138000")),
            VisitorAttribute(key: "name", label: "姓名", value: .string("张三"))
        ]
    )
)

其中 phone、name 需与客服端的访客字段设置一致。配置仅保存本地信息；首次打开客服或需要刷新身份时，应用才会向业务服务端请求令牌。

打开聊天页

在需要咨询入口的按钮事件中调用：

Visitor.openChat(
    from: self,
    options: VisitorChatOptions(groupId: 0)
)

groupId 用于指定客服分组。未填写时使用默认分组；分组对应的接待客服可在分组设置中维护。

传递业务上下文

支持在打开聊天页时一并传递商品、订单或其他业务资料，客服接待时可直接查看。字段格式和完整示例请参阅商品和订单对接。

Visitor.openChat(
    from: self,
    options: VisitorChatOptions(
        groupId: 0,
        contexts: [
            VisitorContext(
                key: "order:ORDER-1001",
                title: "最近订单",
                type: "order",
                fields: [
                    VisitorContextField(key: "status", label: "订单状态", value: "待发货")
                ]
            )
        ]
    )
)

未读计数

可用未读数更新 App 的 Tab 红点或数字。监听对象需要由页面、协调器等宿主对象持有：

final class UnreadObserver: VisitorUnreadListener {
    func onUnreadCountChanged(_ count: Int) {
        // 例如：tabBarItem.badgeValue = count > 0 ? "\(count)" : nil
    }
}

let unreadObserver = UnreadObserver()
try Visitor.addUnreadListener(unreadObserver)

Visitor.unreadCount { result in
    if case let .success(count) = result {
        // 需要时立即使用当前未读数
    }
}

首次成功取得未读数和后续数值变化都会通知监听器。不再需要时调用 try Visitor.removeUnreadListener(unreadObserver)。

媒体权限

如果应用启用了拍照、相册或语音功能，请在 Info.plist 中补充相机、相册和麦克风的用途说明，并在真机上完成授权测试。