WebLiveHub SDK
v1.0.4

Fast, Secure & Scalable Streaming Integration

Use a Hosted Backend (proxy layer) with Composer to unify auth, token exchange & iframe embedding while minimizing key exposure.

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.

 🔒 Zero Key Exposure ⚡ Instant Embed

Quick Start

4 steps to minimum viable integration (MVI)

1

Create Backend

Configure hosted backend

The "Hosted Backend" page will automatically generate the corresponding backend endpoint and configuration for you. Simply follow the UI to create it, copy the generated endpoint, and use it in your server-side code.

  1. Go to "Hosted Backends" management page
  2. Click "New Backend"
  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 the Console "Users" section to create or select an account and obtain its user_id and password for WLSDK::setup().

  1. In navigation click "Users" to open the list.
  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-php
  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 => '' 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(, 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.
Label Role Free
live host YES
connect host YES
live-client viewer YES

⚡ Advanced Features

  • Real‑time Analytics

    Provides latency, request volume and error ratio overview (not a full report) to assist troubleshooting.

  • Vertical & Horizontal Scaling

    Supports multi‑node / multi‑region deployment and edge/cache tiers for elastic scaling.

🔐 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.