原生 iOS 接入

原生 iOS SDK 用于在 App 内打开完整的访客聊天页面。普通接入使用 VisitorUIKit；如果需要自行开发聊天界面，可使用底层的 VisitorCore。

接入准备

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

配置访客身份

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

import VisitorUIKit

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: "待发货")
                ]
            )
        ]
    )
)

媒体权限

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

增值服务

原生 iOS 接入属于增值服务。如需获取 iOS SDK 源码包或安排接入支持，请联系我们。