WebLiveHub SDK

v1.0.4

將直播嵌入到您的產品中

使用具有託管後端的 WebLiveHub PHP SDK 來設定身份驗證、生成流嵌入並在伺服器上保留長期憑證。

開始使用 Composer安裝

🚀 託管後端代理

集中式代理隱藏長期金鑰，強制執行來源控制並實現統一輪換。

📦 Composer發布

安裝&透過 Composer 更新以避免手動打包。

🔒 伺服器端金鑰處理

快速入門

最小可行整合 (MVI) 的 4 個步驟

建立整合端點

設定託管後端端點

在控制台中，「建立」→「整合端點」會自動產生後端端點和設定。請在此建立端點，並將產生的 URL 複製到伺服器端程式碼中。

在控制台導覽中，開啟「建立」→ 「整合端點」。
點選「新增整合端點」
輸入有意義的標籤名稱（例如 Production-api）
複製產生的後端端點

提示：託管後端提供具有隱藏金鑰管理的統一 API 代理程式。

準備使用者憑證（user_id / 密碼）

使用控制台「建立」→「SDK 使用者」建立或選擇帳戶，並取得 WLSDK::setup() 的 user_id 和密碼。

在控制台導覽中，開啟「建立」→ 「SDK 使用者」。
建立或選擇帳戶並在詳細視圖中記下其 user_id。
設定或確認帳戶密碼（僅內部儲存）。
初始化 WLSDK::setup() 時使用此 user_id / 密碼。

安裝PHP SDK

透過 Composer 安裝 WebLiveHub PHP SDK

composer require weblivehub/sdk

提示：此命令會自動下載並安裝所需的依賴項

初始化 SDK 客戶端 + 流令牌產生和嵌入

設定基本 SDK 設定和依賴項

使用設定的 SDK 整合播放器和動態身份驗證。

整合流程概述

佔位符註釋

AUTH_USER_ID：用於與後端進行認證或取得Token的識別碼。它可能是觀眾或串流媒體，具體取決於所選的主機標籤。
AUTH_PASSWORD：AUTH_USER_ID對應的密碼或secret。安全性儲存在伺服器上；切勿在前端或範例程式碼中進行硬編碼。
STREAMER_USER_ID：主播標識符（user_id）。
HOSTED_BACKEND_ENDPOINT：託管後端端點 URL（在範例中顯示為佔位符；實際上透過環境或伺服器設定進行設定）。

建立託管後端： 取得專用後端端點。
Composer安裝： composer require weblivehub/sdk
WLSDK::setup() 設定：
- 放 hb_endpoint （步驟 1 中的後端 URL）
- 提供 user_id 和 password （使用者授權）
輸出 iframe：single = iframe();多重/延遲=lazyIframe()。
完成：內部處理令牌和身份驗證交換。

單一 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.