簡介

1.基本描述

  保利威直播源自公司多年影片技術累積，基於專業的跨平台視訊編解碼技術和大規模視訊內容分發網路，提供穩定流暢、低延遲、高並發的即時音視訊服務。

  保利威直播Java SDK讓您不用複雜程式設計即可輕鬆接入保利威直播影片雲端服務，實現雲端直播相關影片服務。

  保利威直播Java SDK依託保利威直播API實現，對其進行包裝和最佳化。解放B端用戶的共性工作。將API呼叫邏輯和例外處理進行了封裝最佳化，B端用戶只需將請求參數封裝後，交給保利威直播Java SDK處理即可，保利威直播Java SDK處理完成後回傳結果，B端依據回傳資料繼續完成B端業務邏輯。現階段保利威直播Java SDK涵蓋了頻道管理、觀看管理、直播互動、聊天室、播放器等絕大部分經常使用的API操作。

  如果您在使用保利威直播Java SDK的過程中遇到任何問題，直接使用線上客服找到售後技術支援提問。請將問題的執行環境、操作步驟、錯誤回饋資訊、聯絡方式同步提交，便於問題的快速定位和解決。

2.SDK整體設計

1.B端管理員透過SDK建立頻道基本資訊，比如頻道名稱、頻道觀看密碼、頻道直播場景等基本屬性；

2.B端管理員透過SDK對頻道進行基本的資訊設定，比如觀看條件設定、講師基本資訊設定、課程基本資訊設定、分享文案設定等設定；

3.B端講師透過網頁、直播助手、第三方推流工具登入直播頻道，開始直播；

4.C端觀眾透過推廣分享頁面連結或者QR Code登入直播頻道，觀看直播內容；

5.B端待直播結束後，進行回放、轉存設定，統計分析資料獲取，完成直播業務閉環；

3.SDK詳細設計

4.SDK業務邏輯分析

• 前置條件：SDK全域初始化：在呼叫SDK前必須配置全域參數，可配置參數包括帳戶資訊（appId、userId、appSecret) 和HTTP連線池參數（timeout、maxClientNum)，具體請見 初始化
• SDK全域參數注入：SDK將全域配置的參數，注入到請求物件中；
• 簽名生成：SDK採用MD5演算法簽名規則，生成簽名；
• 參數合法性校驗：SDK採用自訂參數校驗工具對輸入參數進行校驗，如有參數不合格，將拋出PloyvSdkException例外，exception的message包括具體校驗不通過的欄位資訊，此例外是執行時期例外，必須捕獲處理相關業務邏輯；
• 發送HTTP請求，獲取回傳資料：SDK在初始化階段初始化了一個HTTP連線池，所有SDK請求都是透過該連線池來發送請求；
• 解析回傳資料：解析回傳資料，如SDK呼叫正常成功，將封裝回應物件，正常回傳，如伺服器回傳錯誤資訊，SDK將將拋出PloyvSdkException例外，exception的message包括具體伺服器執行錯誤資訊，此例外是執行時期例外，必須捕獲處理相關業務邏輯；

5.呼叫流程模板

  上述業務流程圖解析到程式碼層次如下，所有對保利威直播Java SDK的呼叫都可以參考如下呼叫模板（全域初始化只需要全域呼叫一次）。

6.依賴元件版本說明

目前最新版本的保利威 Java SDK 使用的常見元件資訊如下。

Jackson 元件相關建議

如果您的專案也使用了 Jackson 元件，可能存在的風險：當執行時期出現 Jackson 小版本不一致（例如 jackson-databind 與 jackson-core/jackson-annotations 不同小版本，或與你業務中其他依賴要求不一致），可能觸發：

• NoSuchMethodError
• NoClassDefFoundError
• ClassCastException

建議：

1. 在你的專案中統一 Jackson 三件套版本（jackson-bom 或 Spring Boot BOM）。確保 jackson-core / jackson-databind / jackson-annotations 保持同一小版本。
2. 如果你的專案必須使用特定 Jackson 版本（例如因 Spring Boot 管控），可以在引入保利威 SDK 時 排除 Jackson，再由你專案統一提供 Jackson 版本。

範例：排除保利威 SDK 傳遞的 Jackson

<dependency>
  <groupId>net.polyv</groupId>
  <artifactId>polyv-java-live-sdk</artifactId>
  <version>xxx</version>
  <exclusions>
    <exclusion>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-core</artifactId>
    </exclusion>
    <exclusion>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
    </exclusion>
    <exclusion>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-annotations</artifactId>
    </exclusion>
  </exclusions>
</dependency>

<!-- 再由你的项目统一指定 Jackson 版本（示意） -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.fasterxml.jackson</groupId>
      <artifactId>jackson-bom</artifactId>
      <version>${jackson.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

其他常見元件的相關建議

slf4j-api

• Spring Boot 2.x 生態通常仍在 SLF4J 1.7.x 體系
• Spring Boot 3.x 生態升級到 SLF4J 2.0.x
• 建議：
  • 使用 Spring Boot 時，優先讓 Spring Boot BOM 管控日誌相關依賴版本；避免在業務工程裡顯式固定一個與 BOM 不一致的版本。
  • 若你專案顯式引入了 slf4j-simple、log4j-slf4j-impl 等實作，確認只保留一個實作（否則會出現「multiple bindings/providers」類問題）。

httpclient

• HttpClient 4.x (org.apache.http.*) 與 HttpClient 5.x (org.apache.hc.*) 可並存，一般不會有問題，但建議避免在同一專案中混用兩套版本。

排查依賴衝突的推薦方法

在你的專案根目錄執行（Maven）：

1. 查看最終生效版本（建議加 -Dverbose）：

mvn dependency:tree -Dverbose

2. 定位特定元件（範例：Jackson / HttpClient）：

mvn dependency:tree -Dverbose -Dincludes=com.fasterxml.jackson.core:jackson-databind
mvn dependency:tree -Dverbose -Dincludes=org.apache.httpcomponents:httpclient

3. 判斷是誰引入了某個版本（觀察樹上「nearest-wins」路徑），再決定：

• 透過 dependencyManagement 統一版本
• 或在引入點上做 exclusions