BBSport Knowledge Base

Appearance

客服系統 ​

最後更新：2026-04-07

功能說明 ​

提供使用者在 App 各場景聯繫客服的統一入口。支援三種客服線路：DD SDK 客服（主力）、LiveChat SDK 客服、智齒 HTML 客服（H5），後台可透過開關動態設定主線與次線。針對不同情境提供：一般諮詢、充值代客服務（客服充值）、訂單糾紛（含充值失敗自動觸發）、代理營銷客服、專屬福利客服。VIP 會員可聯繫其專屬福利專員（ContactBenefitMemberViewController）。

使用者流程 ​

  1. 使用者在任意頁面點擊客服入口（按鈕、懸浮泡泡、或頁面客服圖示）
  2. 系統呼叫 CustomerChatManager.shared.openChat()
  3. 判斷後台設定是否有可用線路（主線 / 次線）
  4. 若使用者有專屬福利客服場景：彈出含場景選項的進階選擇器（style5 彈窗，顯示主線、次線、及各個專屬場景按鈕）
  5. 若無專屬場景：彈出標準選擇器（style2 弾窗：主線客服一、次線客服一、取消）
  6. 使用者選擇線路後：
    • 選主線或次線 → 依後台設定開啟對應客服（SDK / LiveChat / 智齒 HTML）
    • 選專屬場景 → 呼叫 jumpToBoonCustom(sceneType:) 進入對應場景的 DD SDK 客服
  7. DD SDK 客服開啟：帶入使用者 ID、帳號、VIP 等級、裝置號、進入場景等參數

訂單糾紛流程 ​

  1. 點擊注單、充值單、提款單上的訂單號
  2. 若後台有 SDK 線路，彈出底部浮層（STOrderIDActionView）：「對此訂單有疑問，咨詢客服」/ 「複製單號」
  3. 選擇諮詢客服 → 帶入訂單號與場景類型開啟 SDK 客服

充值失敗自動觸發 ​

  • 充值建立訂單連續失敗 5 次 → 自動開啟客服（createFailRecharge 場景）
  • 充值訂單連續撤銷 3 次 → 自動開啟客服（cancelRecharge 場景）

專屬福利專員聯繫 ​

  1. VIP 首頁顯示「聯繫福利專員」入口
  2. 跳轉至 ContactBenefitMemberViewController
  3. 列出所有福利專員聯繫方式（App 名稱、帳號、聯絡方式）

頁面跳轉 ​

來源頁面操作目標
任意頁面路由 WL://OpenLiveChatVC客服選擇器彈窗 → 對應客服
「我的」首頁 Header點擊客服動畫按鈕（BBMineCustomerServiceButton）客服選擇器彈窗
登入頁點擊「聯繫客服」客服選擇器彈窗
充值頁選擇「客服充值」方式RechargeChatView（聊天室嵌入充值頁）
充值頁輸入區點擊客服按鈕路由 WL://OpenLiveChatVC → 客服選擇器
注單 / 資金明細點擊訂單號STOrderIDActionView 底部浮層 → SDK 客服
VIP 首頁點擊「聯繫福利專員」ContactBenefitMemberViewController
賽事詳情直播場景客服圖示EventDetailCustomServiceView（直播福利客服）
福利中心客服按鈕路由 WL://OpenLiveChatVC
資金明細客服按鈕路由 WL://OpenLiveChatVC
彩票管理客服按鈕路由 WL://OpenLiveChatVC

技術視角（開發看這裡） ​

相關檔案 ​

類型檔案路徑
核心 Manager/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Login_Register/登录注册/Manager/CustomerChatManager.swift
路由註冊/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Login_Register/ModuleApi.m
路由常數 Header/Users/user/Work/bbsport-new/BBSport/Tools/RouterComponent/Classes/Service/IFLoginRegisterConfig.h
路由常數實作/Users/user/Work/bbsport-new/BBSport/Tools/RouterComponent/Classes/Service/IFLoginRegisterConfig.m
推送初始化擴展/Users/user/Work/bbsport-new/BBSport/AppDelegate/AppDelegate+JPPush.swift
SDK 初始化（AppDelegate）/Users/user/Work/bbsport-new/BBSport/AppDelegate/AppDelegate.swift
充值客服聊天 View/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/ChatView/RechargeChatView.swift
充值客服聊天 ViewModel/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/ChatView/RechargeChatViewModel.swift
客服充值碼顯示 View/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/CustomerService/KefuRechargeView.swift
訂單客服浮層定義於 CustomerChatManager.swift 底部（STOrderIDActionView）
專屬福利專員頁/Users/user/Work/bbsport-new/BBSport/Tab/我的/Home/C/ContactBenefitMemberViewController.swift
福利專員 Cell/Users/user/Work/bbsport-new/BBSport/Tab/我的/Home/V/BenefitMemberTableViewCell.swift
福利專員 Model/Users/user/Work/bbsport-new/BBSport/Tab/我的/Home/M/BenefitMembersModel.swift
「我的」客服按鈕/Users/user/Work/bbsport-new/BBSport/Tab/我的/Home/V/BBMineCustomerServiceButton.swift
體育首頁客服按鈕/Users/user/Work/bbsport-new/BBSport/Tab/体育/Sport/Banner/V/HomeNavView.swift
賽事詳情客服 View/Users/user/Work/bbsport-new/BBSport/Tab/体育/Sport/EventDetail/Views/ChatView/ChatCustomService/EventDetailCustomServiceView.swift
懸浮泡泡客服 View/Users/user/Work/bbsport-new/BBSport/STUIKit/STUIComponents/STBusinessUI/STSpecialCustomerView.swift
API（問題列表）/Users/user/Work/bbsport-new/BBSport/API/STAPI/Feedback/STAPI+FeedbackProblemsRequest.swift
API（送出反饋）/Users/user/Work/bbsport-new/BBSport/API/STAPI/Feedback/STAPI+SendFeedbackRequest.swift

API ​

功能說明NamespaceEndpointMethod主要參數
取得福利專員聯繫方式STAPIapi/forehead/system/proxy/config/contactsPOST無
查詢專屬客服場景（有無新訊息）DDConfigManager——userName
問題列表下載按鈕資料DDConfigManager———

DD SDK 客服的通訊均由 DDConfigManager（第三方 SDK DDClientComponent）處理，不經過 STAPI 層，無可暴露的 Endpoint。

資料模型 ​

BenefitMembersModel（福利專員） ​

欄位類型說明
contactString聯繫方式（如帳號 ID）
iconString平台圖示 URL 路徑
nameString軟體名稱（如 Telegram、微信）
proxyNameString代理帳號
proxyIdInt代理 ID

BoonModel（專屬客服場景，DDClientComponent 內部） ​

欄位說明
name場景按鈕名稱
scenesId場景 ID（傳入 SceneType.custom(scenesId)）
hasNewMessage是否有新訊息（控制紅點顯示）
style.leftIcon按鈕左圖示 URL 路徑
style.backgroudColor / style.nightBackgroudColor按鈕背景色（日/夜）
style.textColor按鈕文字色

STCustomerOrderType（訂單類型枚舉） ​

值說明
rechargeIn充值進行中
withdrawIn提現進行中
betOrder投注單
moneyRechage資金明細充值
moneyWithdraw資金明細提現
normal一般（無訂單）

SceneType（進入客服的場景枚舉，傳給 DD SDK） ​

值rawValue說明
normal0普通客服
customerRecharge1代客充值
recharge2充值
withdraw3提現
game4遊戲
custom(Int)Int專屬場景（由後台定義 ID）
cancelRecharge—撤銷充值觸發
createFailRecharge—建立充值訂單失敗觸發

實作重點 ​

  1. SDK 初始化順序（AppDelegate）

    • DDConfigManager.configLocalDomain(clientDomain:) → 設定本地 Domain 快取
    • DDConfigManager.configHost() → 設定 Host（需在 BBMineViewController 初始化前完成）
    • STDomainListManager.setOSSKefuDomain → 取得 OSS 客服 Domain
    • DDConfigManager.registerServices(...) → 完成後呼叫 CustomerChatManager.shared.requestDownloadPages()

  2. 客服線路判斷邏輯（toCheckIsShowLines）

    • 透過 IFMainSwitch.getUrlStr(with: UrlType) 讀取主線/次線設定
    • 值為 "SDK" → DD SDK 客服
    • 值為 "LiveChat" → LiveChat SDK 客服
    • 值為其他非空字串 → 智齒 HTML H5 客服（goZhiChiHtmlKefu）
    • 主線次線都空 → 直接走 DD SDK（預設）

  3. DD SDK 客服參數（goSDKKefu）

    • appId: 固定 "sport"
    • productId: 固定 "bb"
    • mainColor: 固定 "blue"
    • languageType: 固定 "zh_CN"（預留多語言欄位但暫未啟用）
    • cusType: 1 = 會員、3 = 遊客
    • enterScene: SceneType.rawValue
    • rechargeCode: 代客充值碼（無則傳 ""）
    • orderNumber: 訂單號（有糾紛時傳入）
    • notReceivedTips: 充值失敗自動觸發的提示文字

  4. 智齒客服參數（goZhiChiHtmlKefu）

    • AppID: c7e9a12ad95d4fccb3c8450141ea8e5e（固定）
    • 普通渠道 ChannelFlag = "3"、代客充值渠道 RechargeChannelFlag = "5"
    • 未登入以 "体育iOS访客" 作為用戶名

  5. 專屬福利客服（Boon）

    • DDConfigManager.checkHaveBoon(userName:) 輪詢確認是否有新訊息
    • 結果以 BehaviorSubject (haveNewMessageAndBubbleBubblesSubject) 廣播
    • 泡泡氣泡：每個使用者每天只顯示一次（以 UserDefaults key = {userId}-CustomerChatManager-showBubbles 記錄日期）
    • 手動關閉後當天不再顯示（setupTodaySeenBubbles()）

  6. KefuRechargeView（代客充值碼顯示）

    • 固定顯示 4 個格子，每格顯示充值碼的一個字元
    • update(rechargeCode:) 填入碼值；若碼為空則整個 View 隱藏

  7. RechargeChatView（充值嵌入聊天室）

    • 初始化需傳入 eventId、hostId、liveRoomId
    • 透過 RechargeChatViewModel 管理 Socket 連接生命週期
    • 覆寫 hitTest 讓 View 本身不攔截點擊，僅子視圖接收事件

  8. 已知限制

    • 智齒客服 ChannelFlag 原為 4，2024 年改為 3（對齊 Android），已無人了解此參數原始用意
    • 多語言欄位 languageType 預留但目前強制傳 "zh_CN"
    • DD SDK 通訊細節（Domain、API）封裝於 DDClientComponent 外部套件，App 層無法直接查看

API 呼叫流程 ​

客服初始化 (App 啟動時) ​

AppDelegate → STDomainListManager.setOSSKefuDomain()
  └─ DDConfigManager.registerServices() → 初始化客服 SDK
     └─ CustomerChatManager.requestDownloadPages() → 下載 FAQ 頁面

開啟客服 ​

用戶點擊客服按鈕
  └─ CustomerChatManager.openChat(navClassName:, list:, block:)
     ├─ toChoiceLine() → 檢查可用線路
     │
     ├─ 多線路 → 顯示選擇彈窗:
     │  ├─ 主線客服 (UrlTypeServiceMainLine)
     │  └─ 次線客服 (UrlTypeServiceMinorLine)
     │
     └─ showLine(code:, type:) → 開啟對應客服:
        ├─ "SDK" → DD SDK 客服介面
        ├─ "LiveChat" → LiveChat SDK
        └─ URL → 智齒 HTML 客服

客服頻道 ​

ChannelFlag = "3" → 普通客服
RechargeChannelFlag = "5" → 充值專屬客服