Apple FairPlay 集成

了解如何使用 Swift 和 AVFoundation，在 iOS、iPadOS、tvOS 及 Safari 上接入 DRM-X 6.0 FairPlay Streaming，包括服务端授权以及 SPC 请求和 CKC 响应的处理。

查看 Markdown 在线示例更新于 2026-09-21

FairPlay 证书与许可证交互流程

整个交互过程中，SPC 和 CKC 二进制数据必须保持原样。

证书
从获准访问的 URL 加载应用证书。
SPC
使用证书和 HLS 标识符，生成设备的 SPC 请求。
CKC
将 SPC 发送到获准访问的许可证 URL，并接收 CKC 响应。
AVFoundation
将 CKC 交给 AVFoundation，用于播放加密视频。

证书 – SPC 挑战 – CKC 回复 – 本地播放。保留二进制挑战和响应字节不变。

有关 UI 自定义、参数默认值和生命周期示例，请参阅 PLAYER-UI-CONFIGURATION.md。播放器自带的弹出面板均不透明；字幕和水印的不透明度可单独设置。

按照 SDK ZIP 中的 DEMO-QUICKSTART.md 试用 PHP 演示。使用您自己的内容时，请先完成网站/后端集成，再按照 MOBILE-AND-TV-APPS.md 将应用连接到同一套登录系统和观看权限规则。

使用有效的 Professional 或 Enterprise 订阅，从 Console → Developer Tools → Device SDKs 下载 Apple SDK 和 iOS/tvOS 示例应用。

iOS / iPadOS：逐步运行示例#

下载并解压 Apple SDK ZIP。将Package.swift、Sources、Tests和Samples放在一起。在 Mac 上打开 Samples/DrmXAppleSamples.xcodeproj。
选择 DrmXiOS。在 Xcode 的方案菜单中选择DrmXiOS。最低部署目标是 iOS/iPadOS 15。使用 Xcode 26.3 重现此版本的构建检查。
设置签名团队。在应用 Target 中打开 Signing & Capabilities，选择自己的团队和 Bundle Identifier。软件包不包含签名身份。
连接真实设备。通过 Xcode Devices and Simulators 配对 iPhone/iPad，根据提示启用 Developer Mode，并选择该设备作为运行目标。
先阅读 SDK 下载包中的 CUSTOMER-INTEGRATION.md：连接您自己的登录系统、已发布的 Content IDs 和观看权限规则，再运行客户示例。演示内容仅用于评估。
连接自己的应用。按照包 README：通过 File → Add Package Dependencies → Add Local 添加解压后的目录，选择DrmXFairPlay产品。将演示身份验证、端点和 Content IDs 替换为您自己的。

使用 @StateObject 或持有播放器的协调对象保留 DrmXUniversalPlayer，不要在反复计算的 SwiftUI body 中重建它。通过身份验证回调提供已登录观众的 Token。页面真正关闭或用户退出登录时停止播放。

Apple TV：运行 tvOS 示例#

使用相同的 Apple ZIP。打开示例 Xcode 项目并选择DrmXtvOS方案。在 tvOS 目标上设置您的团队和唯一捆绑包标识符。
配对您的 Apple TV。使用 Apple 的配对流程通过 Xcode Devices and Simulators 连接。选择 Apple TV 真机和 Build and Run.
使用遥控器。在播放列表选择 VOD 并按 Select/Play。将焦点移动到跳转、字幕、音频/设置和全屏控件，测试 Back 及播放列表切换。
添加自己的内容。使用与 iOS 相同的 Swift Package 和经过身份验证的 FairPlay 后端。返回已注册的 HLS/CBCS manifest 及受支持的输出策略。

本 SDK 在 tvOS 上仅支持在线播放。 iOS 离线播放所用的 Apple HLS 资源下载 API 在 tvOS 上不可用。iOS/tvOS 模拟器可用于验证布局；FairPlay 必须在已签名的真机应用中测试。目前不提供公开的 IPA 或 TestFlight 下载。

每个视频的菜单都提供 Move up / Move down，在线模式下另有 Download，离线模式下另有 Delete。下载完成后，Download 会被禁用。Downloaded videos 开关用于选择离线播放，此时只能使用已缓存的音轨和字幕。界面不再提供独立的下载、删除或整份播放列表下载按钮。

集成前配置 FairPlay 部署#

在 DRM-X Console 中配置 FairPlay 部署及证书材料。私钥材料以加密形式保留在服务器端。为待测试的 Content ID 发布 HLS/CBCS 版本。

请求 Apple 会话#

从经过身份认证的后端发送 drmSystem: fairplay、manifestTypes: ["hls"] 和适当的 clientPlatform。响应包含已登记的 HLS 播放清单、证书端点、CKC 许可证端点、授权说明和会话释放端点。

原样保留原生字节 除非返回的 Contract 明确要求，否则不要对 SPC/CKC 进行 Base64 转换、JSON 封装或重新解释。代理必须原样转发二进制请求与响应。

AVFoundation 接入步骤#

加载证书。使用返回的短期授权从返回的 FairPlay 证书 URL 中获取它。
生成内容密钥请求数据。使用 HLS 播放列表提供的 skd:// 标识及应用证书。
发送 SPC。通过 POST 向返回的许可证 URL 原样发送 SPC 字节，并原样接收 CKC 字节。
完成请求并释放会话。响应内容密钥请求；观看结束后释放 DRM-X 会话。

Safari 和原生应用验收#

在 iPhone 和 iPad Safari 中测试原生 HLS FairPlay。
在 macOS Safari 中测试可用的 Shaka MSE FairPlay 路径，以及回退到原生 HLS 的情况。
测试原生 iOS、iPadOS 和 tvOS 播放，包括 AirPlay 策略、AV 转接器策略、前后台切换、许可证续期及输出设备变化。
Development 和 Production 使用各自独立的 FairPlay 部署及凭据。

Apple SDK

iOS、iPadOS 和 tvOS 的原生 FairPlay 集成#

Swift Package 面向 iOS 和 tvOS 15+，通过 AVFoundation 的 AVContentKeySession 处理 FairPlay 内容密钥请求，涵盖证书获取、二进制 SPC/CKC 交换、续期、取消及会话释放。

import AVKit
import DrmXFairPlay

let controller = DrmXFairPlayPlayer()
let player = try await controller.prepare(
    endpoint: URL(string: "https://customer.example/api/drmx/playback-session")!,
    contentId: "course-12-lesson-4",
    contentType: .vod,
    customerHeaders: ["Authorization": "Bearer \(customerAccessToken)"]
)
playerViewController.player = player
player.play()

策略模板由后端选择。不要在应用包中放入策略、Manifest URL、Site Key、Access Key 或长期有效的 Token。使用真实 HLS/CBCS 媒体在实体 iPhone、iPad 和 Apple TV 上测试，并验证 HDMI 和 AirPlay 的策略判断。

一个软件包，三种集成方式#

可使用面向 iOS/iPadOS 的 Universal Player、面向 tvOS 的 Universal Player，或上述原生 AVPlayer 集成。它们使用相同的 DrmXFairPlay 软件包和客户播放会话接口。宿主应用负责用户认证，租户凭据保留在后端。

在线播放器支持播放列表、随机与循环播放、可取消的自动播放下一项、续播进度、跳转、倍速、画质偏好、音轨与字幕选择、字幕大小、书签、可选章节和文字稿、A–B 循环、睡眠定时器及全屏。界面适配触摸屏和 Apple TV 遥控器。

let playlist = try DrmXPlaylist(items: [
    DrmXPlaylistItem(contentId: "lesson-1", title: "Getting started"),
    DrmXPlaylistItem(contentId: "lesson-2", title: "Next lesson")
])
let model = DrmXUniversalPlayer(
    endpoint: URL(string: "https://customer.example/api/drmx/playback-session")!,
    playlist: playlist,
    storageNamespace: "your-tenant-and-viewer"
) {
    ["Authorization": "Bearer \(customerAccessToken)"]
}
// Retain the model with @StateObject or an owning coordinator.
DrmXUniversalPlayerView(model: model)
// Stop when the owning screen is actually dismissed.
model.stop()

画质设置仅表达偏好的最高画质，且不得超出会话授权上限。AVPlayer 会根据可用带宽自适应调整；FairPlay 许可证和输出限制始终有效。播放位置和书签按客户及用户命名空间保存，不存储播放凭据。

当前开发版在视频区域内提供上一项、播放/暂停、下一项、CC、设置和全屏控件。播放期间两秒后自动隐藏，触摸或遥控器操作时重新显示。随机播放、循环和 VOD 进度按指定的客户及用户命名空间保存，下载后播放也适用。关闭随机播放和循环时，队列在最后一个视频结束后停止。

iPhone 和 iPad 上受保护的下载

向 DrmXUniversalPlayer 传入已认证的 offlineEndpoint，即可启用下载及已下载视频模式。iOS 使用 AVAssetDownloadURLSession 保存本地 HLS 内容包，并通过 AVContentKeySession 管理绑定到设备的持久 FairPlay 密钥。它只保存不透明的原生密钥和本地元数据，不保存 DRM License Tokens 或明文密钥。下载内容按客户和用户命名空间隔离。离线队列仅包含已完成下载的目录项，并共用保存的进度、随机播放和循环设置。许可证续期需要重新获得在线授权；删除操作只移除选中的下载。

PHP 示例支持 fairplay/hls/ios 持久许可证请求。为每个内容项配置可信的 hlsManifestUrl；证书路径使用新签发 Token 中的有效部署。FairPlay 负责执行过期限制。离线播放只能使用已下载的画质及已缓存的语言轨道。tvOS 使用在线播放器。

截图与录屏行为验证

可在 iPad 和 Apple TV 模拟器中检查布局、播放列表、设置及遥控导航。这些模拟器不支持 FairPlay 播放；SDK 会报告此限制并释放并发播放名额，不会创建不受支持的原生密钥会话。模拟器界面测试不能证明加密播放、离线下载或实体设备验收已通过。

当 iOS 报告正在录屏或镜像输出时，播放器会暂停音视频，并遮盖非活动场景。截屏通知在截屏后才到达，无法修改已保存的图片。