WebLiveHub SDK
v1.0.4

将直播嵌入到您的产品中

使用具有托管后端的 WebLiveHub PHP SDK 来设置身份验证、生成流嵌入并在伺服器上保留长期凭证。

开始使用 Composer安装
🚀 托管后端代理
集中式代理隐藏长期金钥，强制执行来源控制并实现统一轮换。
📦 Composer发布
安装&透过 Composer 更新以避免手动打包。
🔒 伺服器端金钥处理

快速入门

最小可行整合 (MVI) 的 4 个步骤

1

创建整合端点

设置托管后端端点

在控制台中，「建立」→「整合端点」会自动产生后端端点和设置。请在此建立端点，并将产生的 URL 复制到伺服器端程式码中。

  1. 在控制台导览中，打开「建立」→ 「整合端点」。
  2. 点选「新增整合端点」
  3. 输入有意义的标签名称（例如 Production-api）
  4. 复制产生的后端端点
提示：托管后端提供具有隐藏金钥管理的统一 API 代理程式。
2

准备用户凭证（user_id / 密码）

使用控制台「建立」→「SDK 使用者」建立或选择帐户，并取得 WLSDK::setup() 的 user_id 和密码。

  1. 在控制台导览中，打开「建立」→ 「SDK 使用者」。
  2. 建立或选择帐户并在详细视图中记下其 user_id。
  3. 设置或确认帐户密码（仅内部储存）。
  4. 初始化 WLSDK::setup() 时使用此 user_id / 密码。
3

安装PHP SDK

透过 Composer 安装 WebLiveHub PHP SDK

composer require weblivehub/sdk
提示：此命令会自动下载并安装所需的依赖项
4

初始化 SDK 客户端 + 流令牌产生和嵌入

设置基本 SDK 设置和依赖项

使用设置的 SDK 整合播放器和动态身份验证。

整合流程概述

占位符注释
  • AUTH_USER_ID：用于与后端进行认证或取得Token的识别码。它可能是观众或串流媒体，具体取决于所选的主机标签。
  • AUTH_PASSWORD：AUTH_USER_ID对应的密码或secret。安全性储存在伺服器上；切勿在前端或范例程式码中进行硬编码。
  • STREAMER_USER_ID：主播标识符（user_id）。
  • HOSTED_BACKEND_ENDPOINT：托管后端端点 URL（在范例中显示为占位符；实际上透过环境或伺服器设置进行设置）。
  1. 建立托管后端： 取得专用后端端点。
  2. Composer安装： composer require weblivehub/sdk
  3. WLSDK::setup() 设置：
    • 放 hb_endpoint （步骤 1 中的后端 URL）
    • 提供 user_id 和 password （用户授权）
  4. 输出 iframe：single = iframe();多重/延迟=lazyIframe()。
  5. 完成：内部处理令牌和身份验证交换。

单一 Iframe 流嵌入

对单一流使用 WLSDK::iframe()；支援自订属性。

<?php
// === Initialize SDK Client ===

// Include WebLiveHub SDK class
require_once __DIR__ . '/vendor/autoload.php';
use WebLiveHub\SDK\WLSDK;

// Initialize SDK configuration (must complete before first call)
WLSDK::setup([
    'hb_endpoint' => getenv('WL_HOSTED_BACKEND_URL') ?: '<HOSTED_BACKEND_ENDPOINT>',
    'user_id' => '<AUTH_USER_ID>',
    'password' => '<AUTH_PASSWORD>'
]);

?><!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8" />
    <title>WebLiveHub Single Stream Example</title>
    <style>
        /* Set stream container styles */
        #stream-container {
            width: 800px;
            height: 450px;
            border: 1px solid #ccc;
            display: block;
        }
    </style>

    <?php
        // Load official JS SDK (contains frontend logic needed for iframe/lazyIframe)
        echo WLSDK::script();
    ?>
</head>
<body>
<?php
        echo WLSDK::iframe([
            'hostLabel' => 'connect', // Hosted Backend label (connect/live/live-client etc)
            'streamer'  => '<STREAMER_USER_ID>',      // Target streamer's user_id
            'attrs' => [ 'id' => 'stream-container', 'class' => 'wlh-stream', 'style' => 'border-radius:6px;' ]
        ]);
?>
</body>
</html>

多个 Iframe 延迟加载

使用 WLSDK::lazyIframe() 进行具有延迟载入和响应式布局的多重串流显示。

<?php
// === Initialize SDK Client ===

// Include WebLiveHub SDK class
include_once __DIR__.'/vendor/autoload.php';
use WebLiveHub\SDK\WLSDK;

// Initialize SDK configuration
WLSDK::setup([
    'hb_endpoint' => getenv('WL_HOSTED_BACKEND_URL') ?: '<HOSTED_BACKEND_ENDPOINT>',
    'user_id' => '<AUTH_USER_ID>',
    'password' => '<AUTH_PASSWORD>',
]);

?><!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8" />
    <title>Multi Stream Showcase</title>
    <style>body{font-family:system-ui,Arial,sans-serif;margin:24px;background:#fafafa;} .grid{display:grid;gap:20px;grid-template-columns:repeat(auto-fill,minmax(340px,1fr));} .card{background:#fff;padding:12px;border:1px solid #ddd;border-radius:8px;box-shadow:0 2px 3px rgba(0,0,0,.05);} .card h2{font-size:15px;margin:0 0 8px;} </style>

    <?php
        // Load official JS SDK (contains frontend logic needed for iframe/lazyIframe)
        echo WLSDK::script();
    ?>
</head>
<body>
    <h1>Multiple Live Rooms</h1>

    <!-- // === Stream token generation & embed ===  -->
    <!-- // Generate multiple lazy-loaded stream players  -->
    <div class="grid">

        <div class="card">
            <h2>Streamer #1</h2>
            <div>
            <?php
                    // Lazy load (SDK auto-generates token & embeds)
                    echo WLSDK::lazyIframe([
                        'hostLabel' => 'connect',  // Hosted Backend label
                        'streamer' => '<STREAMER_1_USER_ID>'         // Streamer user_id
                    ]);
            ?>
            </div>
        </div>

        <div class="card">
            <h2>Streamer #2</h2>
            <div>
            <?php
                    // Second stream (different streamer; SDK generates corresponding token)
                    echo WLSDK::lazyIframe([
                        'hostLabel' => 'connect',  // Same hosted backend
                        'streamer' => '<STREAMER_2_USER_ID>'         // Different streamer user_id
                    ]);
            ?>
            </div>
        </div>

    </div>
</body>
</html>

🌐 多语言整合（可选）

如果您的网站提供多种介面语言，您可以在呼叫WLSDK时传递lang参数，以保持播放器语言与页面一致。未指定时：WLSDK先读取执行环境语言（在Console中这是目前UI语言环境，默认zh-Hant）；如果不可用，则会回退为英文 (en)。

  • 播放器支援的语言代码：en、ja、zh-Hant、zh-Hans、vi（控制台 UI 目前支援：en、zh-Hant、es）。如果环境语言不在播放器清单中，它会自动回退为 en。
  • 当呼叫 WLSDK::iframe() 或 WLSDK::lazyIframe() 时，加入 lang =>; '<LANG_CODE>'到参数阵列。

范例：将播放器语言设置为繁体中文

以下范例显示在单一 iframe 呼叫中指定 lang => 'zh-Hant'；实际上，您可以使用动态变数。

<?php
// Example: specify the player language in the iframe call
echo WLSDK::iframe([
    'hostLabel' => 'connect',
    'streamer'  => '<STREAMER_USER_ID>',
    'lang'      => 'zh-Hant',
    'attrs'     => [
        'id'    => 'stream-container',
        'class' => 'wlh-stream',
        'style' => 'border-radius:6px;'
    ]
]);

🔔 监听播放器事件

WLSDK产生的播放器不仅仅是一个静态的iframe；您可以注册就绪、结束和 page_unloading 的前端处理程序，以整合 UI 逻辑或日志记录。

  • 建议：使用 WLSDK_attachIframeEventsById(<element id>, handlers) 在前端绑定事件。在 PHP 中输出一个命名的 id，然后在 JS 中使用相同的 id 进行绑定。
  • 相同的绑定适用于 WLSDK::iframe() 和 WLSDK::lazyIframe() 所建立的播放器。
  • 就绪：播放器已载入并就绪（内部握手开始时触发）。
  • 结束：播放结束（直播结束或点播结束）。
  • page_unloading：嵌入页面正在卸载（分页关闭、重新整理或导览离开）。

范例：监听ready/ended/page_unloading事件

此范例显示了常见的事件处理；也提供了通用讯息挂钩来接收其他讯息类型（处理程序签署函数（有效负载，类型））。

<?php
// Example: bind events by element id (recommended)
echo WLSDK::iframe([
    'hostLabel' => 'connect',
    'streamer'  => '<STREAMER_USER_ID>',
    'attrs'     => [
        'id'    => 'stream-with-events',
        'class' => 'wlh-stream',
    ],
]);
?>
<script>
(function(){
    WLSDK_attachIframeEventsById('stream-with-events',{
        'ready': function(){ console.log('player ready'); },
        'ended': function(){ console.log('playback ended'); },
        'page_unloading': function(){ console.log('iframe page unloading'); },
    });
})();
</script>

处理程序以纯 JavaScript 执行；避免将未经过滤的用户输入注入字串中以降低 XSS 风险。

🏷️ 什么是主机标签？

内建使用范例
live = 主持人（广播者）查看（发布/控制）。
live-client = 观看者侧视图（观看/互动）。
connect = 测试/通用连接和快速整合（默认范例）。
根据需要新增自订标签；程式码仅传递标签，而后端解析角色/行为。
  • 前端仅提供标签；后端自动解析角色和节点。
HostLabel 值及其角色
标签 角色 在本指南中使用
观看 主持人 广播公司视图
连接 主持人 测试或一般连接
即时客户端 观众 查看者视图

⚡ 验证边界

  • 在您的环境中验证

    在规划生产使用之前，在您控制的环境中测试嵌入、选定的主机标签和查看者流程。

  • 单独确认操作要求

    本指南不建立生产能力、支援或商业承诺；在生产部署之前使用 WebLiveHub 检查这些内容。

🔐 安全说明

  • 长期金钥保护

    所有长期金钥保留在伺服器上；前端仅使用短暂的授权结果，避免在浏览器中储存原始机密。

  • HTTPS 和 CORS 控制

    在生产中使用HTTPS并限制allow_origins；避免长时间*使用。

  • 代币生命周期

    生命周期和续订由平台后台自动管理；典型的整合不需要额外的手动重新整理流程。

WordPress 整合指南

WebLiveHub Stream（区块优先）文件

此页面重点介绍 PHP SDK 整合路径。如果您要与 WordPress 整合，请使用专用指南：

WordPress 插件整合指南

提示：如果您有书签 #wordpress-plugin，将它们更新为 wordpress_integration_guide.html.