自訂觀眾標籤介面

作用

為不同觀眾動態展示等級、會員身份、認證標識等圖片標籤。標籤顯示在聊天區一般觀眾的暱稱附近。

自訂觀眾標籤介面由觀看端瀏覽器直接請求，不是保利威服務端回呼。觀看端會將設定地址中的佔位符替換為當前觀眾資訊，再將產生的地址作為圖片地址載入。

地址模板

介面地址支援使用佔位符。例如：

https://example.com/viewer-label?userId={userId}

假設當前聊天室使用者 ID 為 viewer_1001，觀看端實際請求的地址為：

https://example.com/viewer-label?userId=viewer_1001

當前支援的佔位符：

佔位符使用規則：

• 佔位符區分大小寫，必須保留英文花括號。
• 同一地址中的多個相同佔位符都會被替換。
• 如果地址中不包含佔位符，所有一般觀眾將載入同一個標籤圖片。
• 不在上表中的佔位符不會被替換，例如 {viewerId}、{userid} 或 %7BuserId%7D。

請求說明

觀看端會將替換後的完整地址直接設定為 <img> 標籤的 src。因此，介面地址及其查詢參數對終端使用者可見，介面不能依賴保利威服務端 IP、回呼簽名或自訂請求頭完成鑑權。

回應要求

客戶介面必須直接回傳瀏覽器可載入的圖片資源。

回應範例：

HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: private, max-age=300

<图片二进制数据>

不要回傳 JSON、HTML、Base64 文字或圖片 URL 字串。例如，{"imageUrl":"https://example.com/label.png"} 無法作為標籤圖片展示。

標籤在頁面中的展示高度為 14px，寬度會按原圖比例自適應。建議使用透明背景的橫向圖片，並提供適合高解析度螢幕顯示的清晰圖片資源。某個觀眾沒有標籤時，建議回傳有效的透明圖片，避免出現圖片載入失敗的圖示。

如何設定

1. 登入直播管理後台。
2. 進入【設定】→【開發設定】→【回呼與介面】→【介面設定】。
3. 在【自訂觀眾標籤介面】中填寫地址模板並儲存。

該設定為帳號級設定，帳號下的頻道共用同一地址模板。清空介面地址並儲存後，將不再展示自訂觀眾標籤。

注意事項

• 建議使用 HTTPS 地址。HTTPS 觀看頁載入 HTTP 圖片時，可能被瀏覽器作為混合內容封鎖。
• 介面需要能夠被觀看端瀏覽器從公網直接存取。一般跨域 <img> 圖片展示通常不要求設定 CORS；如果服務端啟用了防盜鏈，請確保觀看頁可以正常存取圖片。
• 不要在設定地址中放置 AppSecret、固定存取權杖等敏感資訊，完整地址可能出現在頁面原始碼、瀏覽器網路面板及存取日誌中。
• 請根據存取量做好並發控制、限流和快取。標籤內容會變化時，可透過 Cache-Control、ETag 或地址中的固定版本參數控制快取。
• 請校驗 userId 參數，不要直接將其拼接到檔案路徑或資料庫語句中。
• 僅一般觀眾展示自訂標籤，講師、助教、管理員等特殊身份不展示。
• 介面請求失敗或回傳的內容無法解析為圖片時，對應標籤將無法正常展示。