廣場與直播（開發文檔）

最後更新：2026-04-10

📖 功能說明請參考廣場與直播

架構

相關檔案

ViewController（4 個）

檔案	說明
`.../Activity/C/BBMineNewsViewController.swift`	廣場主頁 H5 容器
`.../Stream/StreamerViewController.swift`	主播直播
`.../FullScreenLive/STFullAmuseHostViewController.swift`	全螢幕直播
`.../Activity/C/BBActivityViewController.swift`	活動頁

基礎路徑：BBSport/Tab/广场/

ViewModel（4 個）

檔案	說明
`.../Stream/StreamerViewModel/StreamerViewModel.swift`	主播直播 ViewModel
`.../FullScreenLive/VM/STFullAmuseHostViewModel.swift`	全螢幕 ViewModel
`.../FullScreenLive/Gift/VM/STGiftListViewModel.swift`	禮物列表 ViewModel
`.../FullScreenLive/LiveBetGame/LiveBetGameViewModel.swift`	競猜 ViewModel

基礎路徑：BBSport/Tab/广场/

View（18 個）

檔案	說明
`.../FullScreenLive/Gift/STGiftListView.swift`	禮物列表
`.../FullScreenLive/V/STFullAmuseBGView.swift`	全螢幕背景
`.../FullScreenLive/V/STFullAmuseChatView.swift`	全螢幕聊天
`.../FullScreenLive/V/STFullAmuseMoreFeaturesView.swift`	更多功能
`.../FullScreenLive/V/STFullAmuseHostInfoView.swift`	主播資訊
`.../FullScreenLive/V/STFullAmuseGuideView.swift`	引導
`.../FullScreenLive/V/STFullAmuseAirPlayStatusView.swift`	AirPlay 狀態
`.../FullScreenLive/V/STFullAmuseEntryAnimationView.swift`	入場動畫
`.../FullScreenLive/V/NewFullAmuseMoreLiveView.swift`	更多直播
`.../Stream/Header/StreamerTitleView.swift`	主播標題
`.../Stream/QuickGame/QuickGameView.swift`	快速遊戲
`.../Activity/V/BBActivityCell.swift`	活動 Cell
`.../Activity/V/BBNavSelectionView.swift`	導航選擇
以及 Extension 檔（TurnTableGame / MoreLive / BallView）...

基礎路徑：BBSport/Tab/广场/

Service / Manager（5 個）

檔案	說明
`.../STChatView/STChatManager.swift`	聊天 Socket 管理
`.../STChatView/STChatAPI.swift`	聊天 API
`.../STChatView/VM/STChatViewModel.swift`	聊天 ViewModel
`BBSport/STUIKit/STSportCoreDataCenter/SportDataManager/SportDataManager.swift`	賽事數據管理（提供主播直播源）
`BBSport/STUIKit/STFoundation/Live/LiveComponent.swift`	直播元件（提供 `getVideoSource()` 視頻源、特權排序邏輯）

基礎路徑（前三項）：BBSport/Tab/广场/FullScreenLive/

播放器（4 個）

檔案	說明
`BBSport/Tools/AVPlayerManager/STAVPlayerManager.swift`	全域單例管理器
`BBSport/Tools/AVPlayerManager/STAVPlayerView.swift`	播放器 View
`BBSport/Tools/AVPlayerManager/STPlayerItem.swift`	播放器 Item
`BBSport/Tools/AVPlayerManager/STVideoPlayerLayerView.swift`	影片圖層

Bridge / H5（2 個）

檔案	說明
`BBSport/Tools/STWebViewManager/STBridgeH5WebView.swift`	H5 Bridge 核心
`BBSport/Tools/STWebViewManager/STWebviewBridgeApi.swift`	JS→原生跳轉

API

禮物與送禮

禮物列表

POST api/forehead/live/load/gift — urlForm — STAPI.LiveGiftListRequest

參數	型別	必填	說明
matchType	String	✅	`"体育"` 或 `"娱乐"`

Response：

STGiftModel 欄位（16 個）

欄位	型別	說明
id	Int	禮物 ID
name	String	禮物名稱
photoId	String	禮物圖片 ID
fullScreenPhotoId	String	全螢幕動效圖片 ID
amountDouble	Float	禮物價格（API 欄位 `amount`）
type	Int	禮物類型（0=現金, 1=金幣）
goldAmount	Int	金幣額度
giftLevel	Int	禮物級別（0=平庸, 1=普通, 2=全螢幕炫酷）（API 欄位 `level`）
giftDuration	Float	顯示時間（API 欄位 `showDuration`）
landscape	Bool	是否橫屏
giftNumber	Int	禮物數量
userId	String	使用者 ID
userIcon	String	使用者頭像
userName	String	使用者名稱
isSelect	Bool	是否被選中
isBeSelected	Bool	是否選中

送禮物

POST api/forehead/live/submit/gift/present — urlForm — STAPI.SendGiftRequest

參數	型別	必填	說明
liveRoomId	String	✅	直播間 ID
giftId	String	✅	禮物 ID
giftCount	String	✅	禮物數量

Response： 成功 code=1/429，data=null。code=300000 金幣不足，data=不足金額(Double)。

金幣商城餘額

POST api/forehead/activity/goldmall/balance — urlForm — STAPI.GoldMallBalanceRequest

無參數（需 Authorization）。Response： coinBalance(Int)。

禮物排行榜 Top5

POST api/forehead/live/room/gift/top5 — urlForm — STAPI.GetTopRankGiftListRequest

參數	型別	必填	說明
liveRoomId	Int	✅	直播間 ID

Response：

欄位	型別	說明
cashGiftTop5	[STGiftRankTableCellModel]	現金禮物前 5
goldGiftTop5	[STGiftRankTableCellModel]	金幣禮物前 5

紅包

紅包查詢

POST api/forehead/live/get/room/redEnvelope — urlForm — STAPI.RedPacketRequest

參數	型別	必填	說明
LiveRoomId	Int（字串傳送）	✅	直播間 ID

Response： STRedPacketInfoModel?（無紅包時 null）

STRedPacketInfoModel 欄位（8 個）

欄位	型別	說明
hasReceived	Bool	是否已領取
sendRecordId	Int	紅包發送記錄 ID
type	Int	紅包類型（1=固定金額, 2=拼手氣, 3=紅包雨）
times	Int	倒計時秒數（>0 有效）
obtainPrize	Bool	是否達成參與條件
obtainPrizeDesc	String	達成條件說明
endBettingTime	String	統計結束時間（字串格式）
endBettingTimestamp	Double	統計結束時間（毫秒 timestamp，v5.3.0+ 優先使用）

領取紅包

POST api/forehead/live/submit/receive/redEnvelope — urlForm — STAPI.ReceiveRedPacketRequest

參數	型別	必填	說明
LiveRoomId	Int（字串傳送）	✅	直播間 ID
sendRecordId	String	✅	紅包發送記錄 ID

Response： Double?（領取金額）

其他 API

聊天舉報列表

POST api/forehead/live/chat/report/cate — urlForm

無參數。Response： [String]（舉報類別名稱）

大額曬單設定

POST api/forehead/live/showorder/config — urlForm

無參數。Response： amount(Int, 大額定義金額), isGlobal(Int, 1=開啟)

直播訂閱資訊

POST api/forehead/live/user/subscribe/info — urlForm

無參數。Response： subscribeHostId([Int]), subscribeMatchId([Int])

JS Bridge 支援

type	跳轉目標
`funAnchor`	主播直播間（需登入）
`sportDetail`	賽事詳情
`rechargeIndex`	充值頁
`welfareCenter`	福利中心
`openCustomerService`	客服

播放器

框架：Apple AVPlayer（AVFoundation），無第三方播放器
串流協議：HLS（M3U8）為主，RTMP 已棄用
重試機制：5 秒週期，最多 3 次
前後景：進背景暫停（AirPlay 除外），回前景自動播放
浮動小窗：isFloating=true 時播放器移至 window 上方

播放器常見錯誤排查

黑屏無畫面：檢查 urlString 是否為空、M3U8 連結是否過期、Referer Header 是否正確
重試上限：retryCount >= 3 後停止重試，觸發 hudError() 並透過 delegate 回報 AirPlayStatus.fail；確認網路狀態和直播源是否仍有效
readyToPlay 一直 false：AVPlayerItem status 未進入 .readyToPlay，可能是源格式問題或 CDN 異常
AirPlay 場景：進背景時 AirPlay 不暫停，回前景時需確認 player rate 是否正確恢復

關鍵數字

播放器重試：5 秒週期，最多 3 次
特權主播排序：樂享 > 純特權 > 一般

全螢幕 vs 主播直播進入條件

條件	進入頁面	說明
`isHorizontalScreen == false`（豎屏）	`STFullAmuseHostViewController`	全螢幕直播頁，用於娛樂主播豎屏場景
`isHorizontalScreen == true` 或預設橫屏	`StreamerViewController`	主播直播頁，體育賽事預設進此頁
從「更多直播」切換（在 StreamerVC 內）	`STFullAmuseHostViewController`	點擊豎屏主播時切換
從「更多直播」切換（在 FullAmuse 內）	`StreamerViewController`	點擊橫屏主播時切換
JS Bridge `funAnchor`	`StreamerViewController`	H5 廣場點擊娛樂主播跳轉

判斷來源：SportComponent 根據 isHorizontalScreen 決定實例化哪個 VC；「更多直播」面板根據目標主播方向切換。

實作重點

特權主播排序：liveGroupUserType > 0（樂享）最前 → liveUserGroupId > 0（特權） → 一般主播
「特權」與「樂享」概念：liveUserGroupId > 0 表示該主播屬於「特權主播」群組，只有 IFUserModel.liveRoomIdSpecial 中包含該房間 ID 的用戶才能進入；liveGroupUserType > 0 表示「樂享主播」，是特權的進階版（樂享主播的 liveUserGroupId 也必定 > 0），排序時樂享優先於純特權
特權判斷：讀 IFUserModel.liveRoomIdSpecial（逗號分隔房間 ID）比對
直播源取得：賽事主播從 SportDataManager（BBSport/STUIKit/STSportCoreDataCenter/SportDataManager/SportDataManager.swift）取得；賽事視頻從 LiveComponent.getVideoSource()（BBSport/STUIKit/STFoundation/Live/LiveComponent.swift）取得
視頻 Referer：賽事視頻在 AVURLAsset Header 加 Referer
橫屏判斷：TransferTutorial 強制橫屏；其餘讀 ext 的 isHorizontalScreen

廣場與直播（開發文檔） ​

架構 ​

相關檔案 ​

API ​

禮物與送禮 ​

禮物列表 ​

送禮物 ​

金幣商城餘額 ​

禮物排行榜 Top5 ​

紅包 ​

紅包查詢 ​

領取紅包 ​

其他 API ​

聊天舉報列表 ​

大額曬單設定 ​

直播訂閱資訊 ​

JS Bridge 支援 ​

播放器 ​

全螢幕 vs 主播直播進入條件 ​

實作重點 ​

廣場與直播（開發文檔）

架構

相關檔案

API

禮物與送禮

禮物列表

送禮物

金幣商城餘額

禮物排行榜 Top5

紅包

紅包查詢

領取紅包

其他 API

聊天舉報列表

大額曬單設定

直播訂閱資訊

JS Bridge 支援

播放器

全螢幕 vs 主播直播進入條件

實作重點