WebLiveHub SDK
v1.0.4

Embed live streaming into your product

Use the WebLiveHub PHP SDK with a Hosted Backend to configure authentication, generate stream embeds, and keep long-term credentials on your server.

Get Started Composer Install
🚀 Hosted Backend Proxy
Centralized proxy hides long‑term keys, enforces origin controls and enables unified rotation.
📦 Composer Release
Install & update via Composer to avoid manual packaging.
🔒 Server‑side Key Handling

Quick Start

4 steps to minimum viable integration (MVI)

1

Create an integration endpoint

Configure a hosted backend endpoint

In the Console, Build → “Integration endpoints” automatically generates the backend endpoint and configuration. Create an endpoint there, then copy its generated URL into your server-side code.

  1. In Console navigation, open Build → "Integration endpoints".
  2. Click "New integration endpoint"
  3. Enter meaningful label name (e.g. production-api)
  4. Copy the generated backend endpoint
Tip:Hosted backend provides a unified API proxy with hidden key management.
2

Prepare user credentials (user_id / password)

Use Console navigation Build → “SDK users” to create or select an account and obtain its user_id and password for WLSDK::setup().

  1. In Console navigation, open Build → "SDK users".
  2. Create or select an account and note its user_id in the detail view.
  3. Set or confirm the account password (store internally only).
  4. Use this user_id / password when initializing WLSDK::setup().
3

Install PHP SDK

Install WebLiveHub PHP SDK via Composer

composer require weblivehub/sdk
Tip:This command downloads and installs required dependencies automatically
4

Initialize SDK Client + Stream Token Generation & Embed

Configure base SDK settings & dependencies

Use the configured SDK to integrate player & dynamic auth.

Integration Flow Overview

Placeholder notes
  • AUTH_USER_ID：Identifier used to authenticate with the backend or obtain a Token. It may be a viewer or a streamer depending on the selected hostLabel.
  • AUTH_PASSWORD：The password or secret corresponding to AUTH_USER_ID. Store securely on the server; never hardcode in frontend or sample code.
  • STREAMER_USER_ID：Streamer identifier (user_id).
  • HOSTED_BACKEND_ENDPOINT：Hosted Backend endpoint URL (shown as a placeholder in examples; in practice configure via environment or server settings).
  1. Create hosted backend: obtain dedicated backend endpoint.
  2. Composer install: composer require weblivehub/sdk
  3. WLSDK::setup() config:
    • set hb_endpoint (backend URL from step 1)
    • provide user_id and password (user auth)
  4. Output iframe: single = iframe(); multiple/deferred = lazyIframe().
  5. Done: token & auth exchange handled internally.

Single Iframe Stream Embed

Use WLSDK::iframe() for a single stream; supports custom attributes.

<?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>

Multiple Iframes Lazy Loading

Use WLSDK::lazyIframe() for multi‑stream display with lazy loading & responsive layout.

<?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>

🌐 Multi-language integration (optional)

If your site offers multiple interface languages, you can pass a lang parameter when calling WLSDK to keep the player language consistent with the page. When not specified: WLSDK first reads the execution environment language (in the Console this is the current UI locale, default zh-Hant); if unavailable it falls back to English (en).

  • Player supported language codes: en, ja, zh-Hant, zh-Hans, vi (Console UI currently supports: en, zh-Hant, es). If the environment language is not in the player list it automatically falls back to en.
  • When calling WLSDK::iframe() or WLSDK::lazyIframe(), add lang => '<LANG_CODE>' to the parameter array.

Example: Set player language to Traditional Chinese

The following example shows specifying lang => 'zh-Hant' in a single iframe call; in practice you can use a dynamic variable.

<?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;'
    ]
]);

🔔 Listen to player events

The WLSDK-generated player is not just a static iframe; you can register frontend handlers for ready, ended, and page_unloading to integrate UI logic or logging.

  • Recommended: bind events on the frontend with WLSDK_attachIframeEventsById(<element id>, handlers). Output a named id in PHP, then bind using the same id in JS.
  • The same binding works for players created by WLSDK::iframe() and WLSDK::lazyIframe().
  • ready: Player loaded and ready (fires when internal handshake begins).
  • ended: Playback ended (live finished or VOD reached the end).
  • page_unloading: Embedded page is unloading (tab close, refresh, or navigate away).

Example: Listen to ready / ended / page_unloading events

The example shows common event handling; a generic message hook is also provided to receive other message types (handler signature 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>

Handlers execute as plain JavaScript; avoid injecting unfiltered user input into strings to reduce XSS risk.

🏷️ What is hostLabel?

Built‑in Usage Examples
live = Host (broadcaster) view (publish / control).
live-client = Viewer side view (watch / interact).
connect = Test / generic connection & quick integration (default sample).
Add custom labels as needed; code passes only the label while backend resolves role/behavior.
  • Frontend only supplies label; backend resolves role & node automatically.
HostLabel values and their roles
Label Role Use in this guide
live host Broadcaster view
connect host Test or general connection
live-client viewer Viewer view

⚡ Verification boundaries

  • Validate in your environment

    Test the embed, selected host label, and viewer flow in an environment you control before planning production use.

  • Confirm operating requirements separately

    This guide does not establish production capacity, support, or commercial commitments; review these with WebLiveHub before a production rollout.

🔐 Security Notes

  • Long‑term Key Protection

    All long-term keys remain on the server; the frontend only uses short-lived authorization results, avoiding storing raw secrets in the browser.

  • HTTPS & CORS Control

    Use HTTPS in production and restrict allow_origins; avoid prolonged * usage.

  • Token Lifecycle

    Lifecycle and renewal are managed by the platform backend automatically; typical integrations do not require an extra manual refresh flow.

WordPress Integration Guide

WebLiveHub Stream (block-first) documentation

This page focuses on the PHP SDK integration path. If you’re integrating with WordPress, use the dedicated guide:

WordPress Plugin Integration Guide

Tip: If you had bookmarks to #wordpress-plugin, update them to wordpress_integration_guide.html.