客服套件-DDClient（開發文檔）

最後更新：2026-04-10

📖 功能說明請參考客服套件-DDClient

架構

相關檔案

核心配置（9 個）

檔案	說明
`.../Config/DDConfigManager.swift`	初始化入口、域名管理
`.../Config/DDCommonConstant.swift`	常量定義
`.../Config/DDPathConfig.swift`	本地檔案路徑
`.../Config/NetworkingConfig.swift`	網路狀態持久化
`.../Config/DDNotificationCommon.swift`	通知名稱
`.../Config/DDMessageLostManager.swift`	消息補齊
`.../Config/DDColorStyle.swift`	顏色樣式
`.../Config/DDFontConfig.swift`	字體配置
`.../Config/IFDefine.swift`	螢幕常量

基礎路徑：DDClientComponent/Classes/Other/

域名管理（2 個）

檔案	說明
`.../Domain/ClientDomainManager.swift`	環境域名管理
`.../Domain/DomainModel.swift`	域名模型

基礎路徑：DDClientComponent/Classes/Other/

聊天 Controller（14 個）

檔案	說明
`.../DDChatViewController.swift`	聊天主頁
`.../DDChatViewController+Networking.swift`	歷史記錄/招呼語/補齊
`.../DDChatViewController+Message.swift`	普通消息處理
`.../DDChatViewController+SystemMessage.swift`	系統指令處理
`.../DDChatViewController+Event.swift`	UI 事件
`.../DDChatViewController+Keyboard.swift`	鍵盤處理
`.../DDChatViewController+ToolBarDelegate.swift`	工具列代理
`.../DDChatViewController+TableDelegate.swift`	TableView 代理
`.../DDChatViewController+Notification.swift`	通知處理
`.../DDChatViewController+NewInteractive.swift`	新互動邏輯
`.../DDChatViewController+PopDelegate.swift`	Pop 手勢
`.../DDChatViewController+Menu.swift`	選單處理
`.../DDChatViewController+Chat.swift`	聊天相關
`.../DDClientComponent-Bridging-Header.h`	OC/Swift 橋接

基礎路徑：DDClientComponent/Classes/Chat/Controller/

聊天 Model（15 個）

檔案	說明
`.../DDMessageModel.swift`	訊息模型 + DDMessageType
`.../DDParamModel.swift`	外部參數 + CustomerType
`.../DDChannelsModel.swift`	會話頻道
`.../DDCommandDetailModel.swift`	系統指令 + DDCommandType
`.../DDUserManager.swift`	使用者管理單例
`.../DDUploadModel.swift`	上傳檔案
`.../DDOrderDetailModel.swift`	訂單詳情
`.../DDTemplateModel.swift`	消息模板
`.../DDNoticeModel.swift`	通知
`.../DDServiceAccountInfo.swift`	帳戶資訊
`.../PayDetailModel.swift`	支付詳情
`.../DDChatMenuModel.swift`	聊天選單
`.../DDMessageSizeModel.swift`	訊息尺寸計算
`.../DDNoticePhotoModel.swift`	通知圖片

基礎路徑：DDClientComponent/Classes/Chat/Model/

網路層（7 個）

檔案	說明
`.../Http/DDHttpService.swift`	HTTP 基礎類（Moya）
`.../Http/DDHttpService+ServiceCenter.swift`	業務 API 方法
`.../Http/DDLotteryPlatformRequestInfo.swift`	請求配置
`.../Http/DDLotteryPlatformRequestActionType.swift`	Endpoint 枚舉
`.../Http/DDNetworkingManager.swift`	網路管理
`.../Http/DDError.swift`	錯誤模型
`.../Http/HttpMessageManager/DDHttpMessageManager.swift`	HTTP 消息管理

基礎路徑：DDClientComponent/Classes/Other/Network/

Socket 層（5 個）

檔案	說明
`.../DDSocketManager.swift`	WebSocket 管理單例
`.../DDSocketManager+Accept.swift`	接收訊息解析
`.../DDSocketManager+Send.swift`	發送訊息/鑑權
`.../DDSocketManager+Heartbeat.swift`	心跳 10 秒間隔
`.../DDSocketOrginDataModel.swift`	Socket 原始數據 + Cmd 枚舉

基礎路徑：DDClientComponent/Classes/Other/Network/Socket/

問題/訂單 Controller（8 個）

檔案	說明
`.../DDQustionTypeViewController.swift`	詢前頁（技能組選擇）
`.../DDOrderSelectViewController.swift`	訂單選擇頁
`.../DDCryptoOrderSelectViewController.swift`	加密貨幣訂單選擇
`.../DDSubOrderSelectViewController.swift`	子訂單選擇
`.../DDUpdateQustionViewController.swift`	問題更新頁
`.../DDHelpWebViewController.swift`	幫助 WebView
`.../DDBaseQuestionController.swift`	問題基礎 Controller
`.../DDPageRouter.swift`	內部頁面跳轉路由

基礎路徑：DDClientComponent/Classes/Qusition/Controller/（最後兩項在 Other/Base/Controller）

評價/留言/設備（5 個）

檔案	說明
`.../DDEvaluateViewController.swift`	滿意度評價頁
`.../DDDeviceInfoViewController.swift`	設備資訊頁
`.../DDLeaveMessageController.swift`	離線留言主頁
`.../DDLeaveMessageController+Data.swift`	留言資料處理
`.../DDLeaveMessageController+Notification.swift`	留言通知處理

基礎路徑：DDClientComponent/Classes/（DeviceInfo / LeaveMessage）

聊天 View — ChatCell（19 個）

檔案	說明
`.../DDMeChatViewCell.swift`	我方文字
`.../DDMEImageCell.swift`	我方圖片
`.../DDMeVideoCell.swift`	我方影片
`.../DDMeSureOrderCell.swift`	我方確認訂單
`.../DDOtherChatViewCell.swift`	對方文字
`.../DDOtherImageCell.swift`	對方圖片
`.../DDOtherVideoCell.swift`	對方影片
`.../DDOtherSelectOrderCell.swift`	對方選擇訂單
`.../DDOtherSureOrderCell.swift`	對方確認訂單
`.../DDOtherTextBankViewCell.swift`	對方銀行卡文本
`.../DDOtherTextCurrencyViewCell.swift`	對方 USDT 文本
`.../DDOtherTextOrderViewCell.swift`	對方訂單文本
`.../DDOtherTextPhotoViewCell.swift`	對方圖片文本
`.../DDOtherTextUrlViewCell.swift`	對方 URL 文本
`.../DDCommandTableViewCell.swift`	系統指令通用
`.../DDCommandLeaveMessageCell.swift`	系統離線留言
`.../DDCommandNoticeCell.swift`	系統通知
`.../DDCommandPhotoCell.swift`	系統圖片
`.../DDCommandPhotoCollectionViewCell.swift`	系統圖片集合

基礎路徑：DDClientComponent/Classes/Chat/View/ChatCell/

API

所有 endpoint 定義於 DDLotteryPlatformRequestActionType 枚舉。除特別標註外，均為 POST + application/json。所有請求參數經 RSA 加密，封裝為 {"encryptParam": "..."}。

域名與初始化

取得動態域名

POST /domain/info/queryDomainName

回傳 API_URL, WEBSOCKET_URL, LOG_URL（Base64 編碼）。

用戶/Token/會話

用戶資訊 + Token + 會話判斷（三合一）

POST /api/customer/collectionUserToken

三合一 API

一次完成用戶資訊採集 + Token 取得 + 會話有效性判斷，減少首屏請求。

Request：

參數	型別	說明
userName	String	使用者名稱（遊客模式傳 productId）
userId	Int	使用者 ID（遊客模式傳 0）
sysTag	Int	固定 `3`（iOS）
visitSource	Int	固定 `3`
vipLevel	Int	VIP 等級
enterScene	Int	進入場景
cusType	Int	1=會員, 2=遊客
deviceCode	String	設備唯一碼（Base64 編碼）

Response： invalidFlag: 1=會話中, 2=無會話, 3=排隊中；含 Token 和用戶資訊。

建立會話

POST /api/customer/channel — 選擇技能組後建立會話，Socket 等待分配客服。

Request：

參數	型別	說明
chatType	Int	聊天類型
orderImgUrls	String	訂單圖片 URL
type	Int	1=會員, 2=遊客
userId	Int	使用者 ID
platformOrder	String	訂單號
userName	String	使用者名稱
triggerId	Int	喚醒場景 ID（0=詢前頁, 1=代客充值, 2=充值未到帳, 3=提現, 4=遊戲, 5=代理, 6=充值撤銷, 7=充值無通道）
rechargeCode	Int	代客充值碼（場景 1 時使用）
platformOrderType	Int	平台訂單類型（1=充值, 2=提現, 3=遊戲）

Response： 會話 channelId，Socket 接收客服分配。

結束會話

POST /api/customer/end

Request：

參數	型別	說明
userId	Int	使用者 ID
endType	Int	1=會話轉接, 2=超時斷開, 3=關閉頁面, 4=排隊離開, 6=客服主動離開

Response： 無 data。

其他會話 API

Endpoint	說明
`/api/customer/leave`	使用者離開頁面
`/api/customer/endQueue`	退出排隊
`/api/cusCustomer/querySessionValid`	會話有效性檢查
`/api/customer/cusLeakageChatList`	消息補齊

消息

發送訊息

POST /api/user/msg

Request：

參數	型別	說明
userId	Int	使用者 ID
channelId	Int	會話 ID
customerId	Int	客戶 ID
msgId	String	訊息唯一 ID
deviceType	String	設備類型
deviceId	String	設備 ID
createTime	Int64	建立時間
chatTime	Int64	聊天時間（同 createTime）
messageType	Int	訊息類型（1=文本, 2=表情, 4=圖片, 5=檔案, 8=影片）
content	String	訊息內容
filePath	String	檔案路徑（圖片/影片時使用）
fileName	String	檔案名稱
width / height	Int	影片尺寸（影片訊息時使用）

Response： 無 data。

歷史聊天記錄

POST /api/cusCustomer/newChatHistoryList

上傳圖片/檔案

POST /api/common/s3/upload — multipart

技能組/問題

查詢問題類型（技能組）

POST /api/cusCustomer/queryCusSkill

下載按鈕資訊

GET /api/common/queryDownloadPages

評價

Endpoint	說明
`/api/cusCustomer/addSatisfaction`	提交評價
`/api/cusCustomer/querySatisfaction`	查詢評價標籤庫
`/api/cusCustomer/querySatisfactionContent`	查詢評價內容

訂單

Endpoint	說明
`/api/platform/search`	搜索注單
`/api/platform/games/list`	遊戲產品列表
`/api/platform/msg/order/confirm`	訂單確認
`/api/platform/push/order/v2`	推送訂單到聊天室
`/api/recharge/find/order`	根據 ID 取得訂單
`/api/cusCustomer/updateRechargeCode`	更新充值碼

其他 API

Endpoint	說明
`/api/common/collection`	採集客戶/遊客資訊
`/api/user/token`	取得會話 Token
`/api/common/information`	採集設備資訊
`/api/cusServer/getDeviceInformation`	取得設備資訊
`/api/common/findAutoReply`	黑名單回覆語
`/api/common/queryDictDetail`	關鍵字查詢
`/api/common/queryCommonConfigs`	通用配置
`/api/customer/queueTips`	排隊提示語
`/api/cusCustomer/queryCusQueue`	排隊人數
`/api/server/entering`	輸入狀態上報
`/api/customer/queryLeaveMessage`	留言配置
`/api/cusCustomer/saveLeaveMessage`	保存留言
`/api/cusCustomer/scenes`	福利客服場景列表
`/api/customer/history/delete`	遊客刪除歷史
`/log/logger/collect`	閃退日誌上報

WebSocket

Socket 指令

指令	說明
`C01`	鑑權請求
`C02`	鑑權失敗
`C03`	鑑權成功
`C04`	設備被擠退
`ping` / `pong`	心跳
`P01`	單用戶消息
`P02`	群組消息
`E01`	錯誤

消息類型 DDMessageType（12 個）

值	說明
1	文本
2	表情
4	圖片
5	檔案
7	系統指令
8	影片
11	銀行卡文本
12	URL 文本
13	圖片文本
15	USDT
16	選擇訂單
17	確認訂單

系統指令 DDCommandType（14 個）

值	說明
-5	排隊等待中
1	匹配客服
2	會話轉接
6	邀請評價
7	客服下線
8	歡迎語
9	結束語
10	中斷會話
11	黑名單
20	客服關閉
23 / 29	通知消息
28	確認訂單
30	撤銷消息
32	刪除歷史

與 BB 主專案整合

初始化流程

觸發客服流程

openChat() → toCheckIsShowLines() → 判斷主線/次線
showLine() 根據設定值判斷："SDK" → DD SDK / "LiveChat" → LiveChat / URL → 智齒 H5 / 預設 → SDK
goSDKKefu() 組裝參數 → DDConfigManager.openSTChat(param:)
訂單入口 orderClick() → 諮詢客服/複製單號 → openSDKChat() 帶訂單號
福利客服 jumpToBoonCustom(sceneType:) → 帶自定義 scenesId

DDClientComponentOptions.json

欄位	說明
canUpVideo	可否上傳影片
needServiceLeave	離開是否呼叫 leave API（BB: true）
clientType	0=官網包, 1=呱呱包, 2=SEO包
hasWelfareButton	技能組顯示福利客服按鈕
hasDownloadButton	技能組顯示下載按鈕（BB: true）
touristCanDeleteRecord	遊客可否刪除歷史
cryptocurrency	加密貨幣訂單樣式
mutableQuestionType	技能組 API 返回值是否為 array
overrideUsername	是否覆蓋 server 給的名稱
hasOnlyDepositWithdrawalTypes	只有充值/提現按鈕

實作重點

第一次域名請求 host 來源：初始 host 來自 configLocalDomain() 傳入的本地 JSON 設定檔（ClientDomainManager.currentJsonDic），由主 App 在啟動時提供（如 BB 的 ClientDomain.shared.domainDicBB）。設定檔中包含各環境的 domian_url（域名請求地址）、api_base_url、socket_url、log_url 等初始值，非 hardcode 在 SDK 中
域名防封：啟動時 /domain/info/queryDomainName 取 Base64 編碼域名，失敗時嘗試 OSS 備援 DDOssUrls
域名取得失敗兜底：主域名請求失敗後，呼叫 doubleCheckOssUrls() 依序嘗試 DDOssUrls（從 UserDefaults "oss.domain.kfUrls" 讀取，測試包為空陣列）。每次失敗移除第一個 URL 並重試。若 OSS 全部失敗，complete(false, ...) 回調失敗，此時客服功能無法使用，使用者點擊客服入口不會有回應（無 Toast 或彈窗提示）
RSA 加密：所有 POST 參數經 DDIFCommonUtil.RSAWith: (OC) 加密，封裝為 {"encryptParam": "..."}。SDK 中無 debug 模式可關閉加密，如需除錯可在 DDLotteryPlatformRequestInfo 的 parameters 計算屬性中加斷點查看加密前的原始參數，或使用 Proxyman 的 Map Local 功能替換回應
消息補齊：DDMessageLostManager 追蹤 sort 值，發現缺漏呼叫 /api/customer/cusLeakageChatList
三合一 API：/api/customer/collectionUserToken 減少首屏請求

關鍵數字

WebSocket 心跳：10 秒間隔
斷線重連：5 秒後自動重連
Header 統一帶 appId, productId, version, deviceType, timestamp, token, language, ip

客服套件-DDClient（開發文檔） ​

架構 ​

相關檔案 ​

API ​

域名與初始化 ​

取得動態域名 ​

用戶/Token/會話 ​

用戶資訊 + Token + 會話判斷（三合一） ​

建立會話 ​

結束會話 ​

其他會話 API ​

消息 ​

發送訊息 ​

歷史聊天記錄 ​

上傳圖片/檔案 ​

技能組/問題 ​

查詢問題類型（技能組） ​

下載按鈕資訊 ​

評價 ​

訂單 ​

其他 API ​

WebSocket ​

Socket 指令 ​

與 BB 主專案整合 ​

初始化流程 ​

觸發客服流程 ​

DDClientComponentOptions.json ​

實作重點 ​

客服套件-DDClient（開發文檔）

架構

相關檔案

API

域名與初始化

取得動態域名

用戶/Token/會話

用戶資訊 + Token + 會話判斷（三合一）

建立會話

結束會話

其他會話 API

消息

發送訊息

歷史聊天記錄

上傳圖片/檔案

技能組/問題

查詢問題類型（技能組）

下載按鈕資訊

評價

訂單

其他 API

WebSocket

Socket 指令

與 BB 主專案整合

初始化流程

觸發客服流程

DDClientComponentOptions.json

實作重點