Lịch sử: Player SDK trên iOS

Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.
02/10/2026 · +55 −56 dòng
Xem thay đổi
- // Wandura playback in an iOS app (Swift 5.9+, iOS 15+). Reviewed by hand: the docs CI runs `swiftc -parse` on this
- // file when the runner has a Swift toolchain, and always checks that brackets balance.
- // Guide: https://docs.wandura.ai/developers/player-sdk/ios
- //
- // The app never talks to Wandura and never holds an API key. It talks to YOUR backend, which applies your paywall
- // and asks Wandura for tickets. Only `PlayerSDK` touches the Player SDK: fill it in with the calls named in the
- // Player SDK guide (partner.wandura.ai → Developers → Player SDK).
- import Foundation
+ # Player SDK trên iOS
  
- // #region sdk
+ > **TL;DR** — Cài `TTSDKFramework` `1.52.100.4-standard` bằng CocoaPods (iOS 11+, Xcode 14+, tắt Bitcode), thêm tệp giấy phép Wandura gửi bạn, khởi động SDK, và đọc hai giá trị thiết bị sau khi qua bước kiểm giấy phép. App gửi chúng về backend **của bạn**, nhận lại vé, và đưa vé cho SDK. Khi SDK báo lỗi, xin **một** vé mới rồi phát tiếp.
+ 
+ ## Điều kiện cần {#prerequisites}
+ 
+ | | |
+ |---|---|
+ | Giấy phép | Tệp `.lic` và App ID từ Wandura, gắn với bundle ID **chính thức** của bạn. Xem [Player SDK](index.md#licence). |
+ | Công cụ | Xcode 14 trở lên, iOS 11.0 trở lên, tắt Bitcode, CocoaPods (luôn mở `.xcworkspace`). |
+ | Thiết bị | Một iPhone thật để phát nội dung mã hoá. |
+ | Backend của bạn | Một endpoint xin vé: [Luồng playback và paywall](../guides/playback-flow.md). |
+ 
+ Các lệnh gọi SDK chính xác (khởi động, thông báo giấy phép, giá trị thiết bị, playback, phụ đề) nằm trong hướng dẫn Player SDK ở partner.wandura.ai → **Developers** → **Player SDK**.
+ 
+ ## Luồng trong app của bạn {#flow}
+ 
+ 1. **Khởi động SDK** lúc mở app bằng App ID và tệp giấy phép, và chờ kết quả kiểm giấy phép trước khi làm bất cứ việc gì khác.
+ 2. **Đọc giá trị thiết bị** (device ID → `union_info`, device public key → `drm_kek`). Không bao giờ gửi `nil`, `"(null)"` hay chuỗi rỗng: hãy ném lỗi (throw) thay vào đó.
+ 3. **Gọi backend của bạn** để phát tập. Backend áp paywall của bạn rồi xin Wandura; app của bạn không bao giờ giữ API key.
+ 4. **Phát**: đưa `vid` và `play_auth_token` cho SDK; thêm phụ đề.
+ 5. **Tải trước** các tập kế tiếp bằng các vé prefetch mà backend trả về.
+ 6. **Khi có bất kỳ lỗi SDK nào** (kể cả vé hết hạn): xin **một** vé mới và phát tiếp tại đúng vị trí. Đừng rẽ nhánh theo mã lỗi SDK, và đừng lặp.
+ 7. **Khi quay lại từ nền (background)**: nếu vé hiện tại còn dưới một phút, hãy thay vé trước khi phát tiếp.
+ 
+ ## Code {#code}
+ 
+ Tệp bên dưới là phía app của luồng đó, viết bằng Swift. Chỉ `PlayerSDK` chạm vào SDK: hãy điền vào đó các lệnh gọi lấy từ hướng dẫn trên portal. Dạng response của backend khớp với [các ví dụ backend Node và Python](../guides/playback-flow.md#code).
+ 
+ ### SDK đứng sau một protocol {#code-sdk}
+ 
+ ```swift
  struct DeviceValues {
      let unionInfo: String // device ID generated by the Player SDK
⋯
      var onError: ((Error) -> Void)? { get set }
  }
- // #endregion sdk
- 
- // #region contract
- struct Subtitle: Decodable {
-     let lang: String
-     let url: URL
-     let format: String
- }
- 
- struct Ticket: Decodable {
-     let vid: String
-     let playAuthToken: String // memory only: never log it, never write it to disk
-     let expiresAt: Date
-     let subtitles: [Subtitle]
- 
-     enum CodingKeys: String, CodingKey {
-         case vid, subtitles
-         case playAuthToken = "play_auth_token"
-         case expiresAt = "expires_at"
-     }
- 
-     /// Wandura's clock decides; allow a minute for a device clock that runs slow.
-     var isFresh: Bool { expiresAt.timeIntervalSinceNow > 60 }
- }
- 
- struct NextTicket: Decodable {
-     let episodeNo: Int
-     let ticket: Ticket
-     enum CodingKeys: String, CodingKey { case ticket, episodeNo = "episode_no" }
- }
- 
- enum Outcome: String, Decodable {
-     case locked, unavailable, busy, broken
-     case notReady = "not_ready"
- }
+ ```
  
- /// The shape the example backends (Node, Python) return from YOUR `POST /v1/play`.
- struct PlayResponse: Decodable {
-     let ok: Bool
-     let current: Ticket?
-     let next: [NextTicket]?
-     let outcome: Outcome?
- }
- // #endregion contract
+ ### Gọi backend của bạn {#code-backend}
  
- // #region backend
+ ```swift
  final class Backend {
      private let baseURL: URL
⋯
      }
  }
- // #endregion backend
+ ```
  
- // #region controller
+ ### Bắt đầu, prefetch, hết hạn vé, lỗi {#code-controller}
+ 
+ ```swift
  enum ScreenState {
      case loading
⋯
      }
  }
- // #endregion controller
+ ```
+ 
+ ## Checklist {#checklist}
+ 
+ - [ ] Kết quả kiểm giấy phép được kiểm tra trước khi đọc giá trị thiết bị.
+ - [ ] Giá trị thiết bị khi gửi không bao giờ là `nil`, `"(null)"` hay rỗng.
+ - [ ] App không chứa key `wnd_live_` nào (tìm trong `.ipa` đã build).
+ - [ ] `play_auth_token` chỉ được giữ trong bộ nhớ: không nằm trong `UserDefaults`, log hay crash report.
+ - [ ] Lỗi SDK dẫn tới một vé mới và phát tiếp, không bao giờ thành vòng lặp.
+ - [ ] Phát tiếp sau hơn 29 phút ở nền thì thay vé trước.
+ - [ ] Tập không có phụ đề vẫn phát mà không báo lỗi.
+ 
+ ## Liên quan {#related}
+ 
+ - [Tổng quan Player SDK và giấy phép](index.md)
+ - [Phát mượt khi tải cao](../guides/smooth-playback.md#in-the-app)
+ - [Phụ đề](../guides/subtitles.md)
02/10/2026 · Tạo trang