WebLiveHub SDK

v1.0.4

ライブ配信をプロダクトに組み込む

WebLiveHub PHP SDK とホステッドバックエンドを使用して認証を設定し、配信の埋め込みを生成して、長期認証情報をサーバー上で安全に管理します。

はじめに Composer でインストール

🚀 ホステッドバックエンドプロキシ

集中管理されたプロキシが長期キーを隠し、オリジン制御と一元的なローテーションを実現します。

📦 Composer リリース

Composer からインストールおよび更新し、手作業でのパッケージ管理を避けられます。

🔒 サーバー側でのキー管理

クイックスタート

最小構成の連携（MVI）までの 4 ステップ

統合エンドポイントを作成

ホステッドバックエンドのエンドポイントを設定

Console の「Build」→「Integration endpoints」では、バックエンドエンドポイントと設定が自動生成されます。そこでエンドポイントを作成し、生成された URL をサーバー側コードで使用してください。

Console のナビゲーションで「Build」→ 「Integration endpoints」を開きます。
「New integration endpoint」をクリック
用途が分かるラベル名を入力（例：production-api）
生成されたバックエンドエンドポイントをコピー

ヒント：ホステッドバックエンドは、キーを非公開で管理する統合 API プロキシを提供します。

ユーザー認証情報（user_id / password）を準備

Console の「Build」→「SDK users」でアカウントを作成または選択し、WLSDK::setup() で使用する user_id と password を取得します。

Console のナビゲーションで「Build」→ 「SDK users」を開きます。
アカウントを作成または選択し、詳細画面の user_id を控えます。
アカウントのパスワードを設定または確認します（内部でのみ保管してください）。
WLSDK::setup() の初期化時に、この user_id / password を使用します。

PHP SDK をインストール

Composer で WebLiveHub PHP SDK をインストール

composer require weblivehub/sdk

ヒント：このコマンドは必要な依存関係を自動的にダウンロードしてインストールします

SDK クライアントの初期化 + 配信トークンの生成と埋め込み

SDK の基本設定と依存関係を構成

設定済みの SDK を使用して、プレーヤーと動的認証を連携します。

連携フローの概要

プレースホルダーの説明

AUTH_USER_ID：バックエンドでの認証または Token の取得に使用する識別子です。選択した hostLabel に応じて、視聴者または配信者になります。
AUTH_PASSWORD：AUTH_USER_ID に対応するパスワードまたはシークレットです。サーバー上で安全に保管し、フロントエンドやサンプルコードに直接記述しないでください。
STREAMER_USER_ID：配信者の識別子（user_id）です。
HOSTED_BACKEND_ENDPOINT：ホステッドバックエンドのエンドポイント URL です（例ではプレースホルダーとして表示し、実際には環境変数またはサーバー設定で指定します）。

ホステッドバックエンドを作成： 専用のバックエンドエンドポイントを取得します。
Composer でインストール： composer require weblivehub/sdk
WLSDK::setup() の設定：
- hb_endpoint を設定（ステップ 1 のバックエンド URL）
- user_id と password を指定（ユーザー認証）
iframe を出力：単一 = 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（Console 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 ではありません。ready、ended、page_unloading のフロントエンドハンドラーを登録し、UI ロジックやログ処理と連携できます。

推奨：フロントエンドで WLSDK_attachIframeEventsById(<element id>, handlers) を使用してイベントをバインドします。PHP で名前付き id を出力し、JS でも同じ id を使用してください。
同じバインド方法を WLSDK::iframe() と WLSDK::lazyIframe() で作成したプレーヤーに使用できます。

ready：プレーヤーの読み込みが完了（内部ハンドシェイクの開始時に発火）。
ended：再生が終了（ライブ終了または VOD の終端に到達）。
page_unloading：埋め込みページが終了処理中（タブを閉じる、更新、別ページへの移動）。

例：ready / ended / page_unloading イベントを受信

この例では一般的なイベント処理を示します。ほかのメッセージ種別を受信するための汎用メッセージフックも利用できます（ハンドラー形式：function(payload, type)）。

<?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 リスクを抑えるため、未検証のユーザー入力を文字列に挿入しないでください。

🏷️ hostLabel とは？

組み込みの使用例
live = ホスト（配信者）画面（配信／制御）。
live-client = 視聴者側の画面（視聴／操作）。
connect = テスト／汎用接続と簡易連携（既定のサンプル）。
必要に応じてカスタムラベルを追加できます。コードはラベルのみを渡し、バックエンドが役割と動作を解決します。

フロントエンドはラベルのみを指定し、バックエンドが役割とノードを自動的に解決します。

HostLabel の値と役割
ラベル	役割	このガイドでの用途
live	host	配信者画面
connect	host	テストまたは汎用接続
live-client	viewer	視聴者画面

⚡ 検証範囲

ご自身の環境で検証
本番利用を計画する前に、管理下の環境で埋め込み、選択したホストラベル、視聴者フローをテストしてください。
運用要件は別途確認
このガイドは本番容量、サポート、商用上の確約を定めるものではありません。本番展開前に WebLiveHub と確認してください。

🔐 セキュリティに関する注意事項

長期キーの保護
すべての長期キーはサーバー上に保持し、フロントエンドでは短期間有効な認証結果のみを使用するため、ブラウザーに生のシークレットを保存しません。
HTTPS と CORS の制御
本番環境では HTTPS を使用し、allow_origins を制限してください。* の継続使用は避けてください。
トークンのライフサイクル
ライフサイクルと更新はプラットフォームのバックエンドが自動管理するため、通常の連携では追加の手動更新処理は不要です。

WordPress 連携ガイド

WebLiveHub Stream（ブロック優先）のドキュメント

このページでは PHP SDK の連携方法を説明します。WordPress と連携する場合は、専用ガイドをご利用ください：

WordPress プラグイン連携ガイド

ヒント：以前のページをブックマークしている場合は、 #wordpress-pluginに更新してください： wordpress_integration_guide.html.