簡介

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端管理員把影片地址分發給C端觀眾，或者把嵌入播放器的觀看頁面地址分發給觀眾。

4、C端觀眾透過開啟觀看地址的連結或者QR Code掃碼觀看B端管理員上傳的影片。

5、B端管理員可查看C端觀眾的觀看情況和統計分析資料，完成點播業務閉環。

3.SDK詳細設計

4.SDK業務邏輯分析

• 前置條件：SDK全域初始化，在呼叫SDK前必須設定全域參數，可設定參數包括帳戶資訊（userId、secretKey) 和HTTP連線池參數（timeout、maxClientNum)，具體請見 初始化。
• SDK全域參數注入：SDK將全域設定的參數，注入到請求物件中。
• 簽名生成：SDK採用點播簽名規則，生成簽名。
• 參數合法性校驗：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