Web 与 HTML5 播放

先运行完整示例#

Web 软件包包含最新的 Universal Player 本地 JavaScript 文件与类型声明、已验证的 Shaka、可运行的 PHP 应用、ASP.NET Core 示例和集成 README。生产页面可从 DRM-X CDN 加载 Shaka 和 Universal Player；软件包同时保留当前版本的本地文件，供审查、开发和受控回退使用。

1. 在服务器端设置 Site ID、Site Key 和 Access Key。
2. 设置可信且状态为 Published 的加密文件 Content ID，并选择命名策略。
3. 将示例中的登录和观看权限判断替换为您的业务逻辑。

客户端所需的最少职责#

<drmx-universal-player
  content-id="your-published-content-id"
  session-endpoint="/api/drmx/playback-session">
</drmx-universal-player>

在加载此组件前，从完整套件加载经过验证的 Shaka 运行库和当前 Universal Player 脚本。观众按 Play 后，组件调用您经过身份验证的端点。该端点检查观众会话和观看权限，选择可信内容和策略，创建 Contract v1，并使用 Cache-Control: no-store 返回。

自动选择 DRM 的规则#

• Windows Microsoft Edge 优先使用 PlayReady。如果已验证的 PlayReady 路径在开始播放前失败，Auto 可在限定条件下回退到 Widevine。
• Chrome 和受支持的 Android 浏览器使用 Widevine。
• iPhone 和 iPad 上的 Safari 使用原生 HLS FairPlay。受支持的 macOS Safari 在可用时优先使用已验证的 Shaka MSE FairPlay，并支持回退到原生 HLS。
• 兼容的华为浏览器使用已验证的 WisePlay 路径，并采取保守的自动画质选择规则。

生产上线检查清单#

• 所有请求均使用 HTTPS，并将 Access Keys 保存在服务器端的密钥配置中。
• 返回播放会话响应时设置 Cache-Control: no-store。
• 不要在 localStorage 中持久保存 Manifest URL、Token 或播放会话响应。
• 详细的脱敏日志应由用户主动开启，并设置记录时限。不要记录许可证二进制数据或授权信息。
• 使用实体设备测试 Windows Edge、macOS Safari、iPhone/iPad Safari、Android，以及您宣称支持的每类设备。

可选的手机专用 1080p 限制#

Web SDK 1.2.0-beta.4 提供可选的手机限制。保持未设置可保留原有 UHD 行为。请在首次按 Play 前配置：

<drmx-universal-player
  content-id="your-published-content-id"
  session-endpoint="/api/drmx/playback-session"
  mobile-max-height="1080">
</drmx-universal-player>

// Equivalent component option; retained for subsequent playlist items:
await component.play({mobileMaximumHeight: 1080});
// Remove the option before a new playback:
await component.play({mobileMaximumHeight: null});

// Low-level API, for a video element you own:
await DrmXUniversalPlayer.start({
  video, contentId: 'your-published-content-id',
  sessionEndpoint: '/api/drmx/playback-session',
  mobileMaximumHeight: 1080
});

此选项仅对检测为手机的设备生效，平板、电脑和电视保留原有上限。检测依据浏览器提示和 user-agent 回退判断，屏幕宽度不决定分辨率。若宿主应用已知设备类别，请使用 device-class="phone" 或 deviceClass: "phone"。其他支持值为 auto、tablet、desktop 和 tv。浏览器分类仅供参考。

SDK 在授权前发送较低的 platformCapabilities.maximumHeight。您的端点必须转发此值或进一步降低。返回的上限不得高于请求值。Auto 和手动画质选择始终处于允许范围内，包括旋转、全屏、重试和切换播放列表之后。已签名的 DRM 策略和解码器限制可能进一步降低可用画质。值必须为 144 到 4320 之间的整数；未设置或 null 会关闭此可选限制。

Safari 需要经过筛选的 HLS

后端应返回绑定到会话的 nativeHlsQuality.autoUrl 和允许的画质 URL，仅包含符合限制的视频版本，同时保留音频和字幕分组。当前完整 PHP 示例已实现此功能。若 HLS 主播放清单仍无限制，仅降低数字上限不能节省带宽。SDK 会拒绝高于请求的上限，以及缺少所需描述信息的限高 FairPlay 响应。其他后端集成必须先实现相同合约，再启用此选项。

原生 SDK 选项

Apple Universal Player 1.0.0-beta.1 接受 mobileMaximumHeight: 1080，且仅对原生手机设备类别生效。其端点必须返回经过筛选的主播放清单，媒体加载前会进行检查。Android 1.0.0-beta.1 的 WidevineCapabilities.playbackCapabilities 接受 mobileMaximumHeight = 1080；手机使用 clientPlatform = "android"，其他设备类别应明确使用 android-tablet 或 android-tv。新下载应使用相应的离线能力限制。已有下载会保留。

验证您的集成

1. 打包加密一个包含 1080p、更低分辨率及 UHD 版本的源文件。确认未设置限制时能够播放。
2. 在手机上启用 1080 限制。检查授权上限、经过筛选的主播放清单、Auto/手动画质菜单和解码视频尺寸。所有允许的选项都不得超过 1080p。
3. 测试跳转、画质切换、音频、字幕、广告和播放列表自动前进。停止播放，并确认会话已释放。
4. 在电脑和平板上使用相同选项：手机专用限制不应降低它们的上限。原有策略或设备限制仍然生效。

分辨率上限不会设置比特率，也不能保证固定的带宽节省量。若规则必须防止浏览器请求被篡改，请在可信后端和匹配的 DRM 策略中执行。切勿将客户端设备提示当作证明。若没有符合限制的视频版本，必须报错，不得静默回退到 UHD。

iPhone Safari 中一致的全屏控件#

Web SDK 1.2.0-beta.4 在全屏中保留 Web Player 控件，包括 PHP 广告页面。在 iPhone 上，支持时使用元素全屏，否则在页面内展开播放器，浏览器栏可能仍然显示。它不会切换到 iPhone 仅包含视频的原生播放器。所有平台均使用同一设置菜单选择画质、音频语言和字幕。

音频和字幕选项反映当前媒体轨道状态，并在原生 HLS 应用更改后更新。关闭再开启 CC 会保留上次选择的字幕语言。广告时段使用独立控件；内容恢复播放后，常规播放控件会重新显示。

测试画质、语言和广告#

1. 通过真实的轻触或点击开始播放。浏览器的自动播放和声音规则仍然适用。
2. 打开设置，检查当前画质、音频和字幕选择。Auto 使用允许的分辨率梯度；手动选择不能提高授权上限。
3. 切换音频语言，选择字幕语言，然后关闭再开启 CC。确认标签反映当前轨道，并保留字幕语言偏好。
4. 在 iPhone Safari 和 Edge 中进入全屏。Web Player 保留共享控件；iPhone 可能在页面内展开，浏览器栏仍然可见。
5. 若集成使用广告，请测试内容播放前、播放中和播放后的广告时段，并包含画质切换测试。PHP 广告页面提供测试工具。内置演示广告与 Google IMA 属于不同模式；应确认所选广告服务能够在每种受支持浏览器中加载。

带宽选项请参阅可选的手机专用 1080p 限制。保持未设置可保留原有 UHD 行为。分辨率限制不会设置固定比特率，也不能保证按百分比节省带宽。