Integration Guide

Download Resources

ZEGO Player Plugin is provided by ZEGOCLOUD. You can obtain the player plugin resources for the Web platform on this page. For release notes, please refer to Player Plugin - Release Notes, and for compliance matters, please refer to ZEGO Security and Compliance White Paper.

Player Plugin 1.5.1

Local Download

Feature Experience

Try It Out

Warning

The Player Plugin is currently in the Beta public testing phase and only supports the Web platform. If you have any questions or business requirements, please contact ZEGO technical support.
The Player Plugin must be used with Express SDK version 3.0.0 or above.

Prerequisites

Before starting the integration of the Player Plugin, ensure that the following requirements are met:

ZEGO Express SDK has been integrated into your project. For details, please refer to Quick Start - Integration.
The CDN address for Stream Publishing and relaying has been generated. For details, please refer to Using CDN for Live Streaming.

Integration Guide

Important Notes

All files of the Player Plugin package need to be deployed on a static server. In HTML, use the <script> tag to import the file ZegoExpressPlayer-1.3.0.js (the version number can be changed according to the actual downloaded package). This JS file will request related resource dependencies after the <script> tag is loaded.
The Player Plugin instance depends on and controls a specified container <div> tag on the page to play media resource screens. Therefore, you need to add an empty <div> tag to the page as a container and hand it over to the Player Plugin for control to ensure normal media resource playback.
Currently, the Player Plugin only supports integration via the <script> tag and does not support npm integration.

If your business project uses npm integration, during the integration of the Player Plugin, you need to ensure that package.json is configured with "homepage" as the current directory when packaging with npm to ensure that the relative paths for Player Plugin resource requests are correct. If you have not configured it yet, please add the configuration option in package.json:
```
{
    "homepage" : ".",
    ...
}
```
```
{
    "homepage" : ".",
    ...
}
```

Integration Process Example

The following section describes the process of integrating the Player Plugin in detail.

Create Test Project Files

Create a new folder "zego-express-player-demo" locally.
Obtain the latest Express SDK JS integration package (must be version 3.0.0 or above) from the Download page.
Obtain the latest Player Plugin package from this page. All files in the unzipped directory need to be used and must be placed in the same directory on the server, and cannot be deployed across domains from the page address.

The new directory structure is as follows:

Test project root directory
- zego-express-player-demo
    |--- zego-express-engine-webrtc   # Place the Web Express SDK JS integration package (SDK version >= 3.0.0) in this directory
        |--- ...
        |--- ZegoExpressWebRTC-3.0.0.js
    |--- zego-express-player  # Place all files from the downloaded Player Plugin package in this directory
        |--- ...
        |--- ZegoExpressPlayer-1.3.0.js
    |--- demo.html

Test project root directory
- zego-express-player-demo
    |--- zego-express-engine-webrtc   # Place the Web Express SDK JS integration package (SDK version >= 3.0.0) in this directory
        |--- ...
        |--- ZegoExpressWebRTC-3.0.0.js
    |--- zego-express-player  # Place all files from the downloaded Player Plugin package in this directory
        |--- ...
        |--- ZegoExpressPlayer-1.3.0.js
    |--- demo.html

Import Express SDK and Player Plugin

In the demo.html file, use the <script> tag to import the Express SDK (must be version 3.0.0 or above) and the Player Plugin package.
At the same time, create an empty <div> tag with an id name of "player-container" (id can be modified) as the Player container and configure the width and height of the container.

Player Component Container Related Configuration Description:
- zg-width, the width of the Player component, optional. If only the width is set, the height of the rendered component will be scaled proportionally according to the video aspect ratio.
- zg-height, the height of the Player component, optional. If only the height is set, the width of the rendered component will be scaled proportionally according to the video aspect ratio.
- If neither is set, the rendered component will be displayed directly according to the video resolution.

...
<body>
    ...
    <div id="player-container" zg-width="640" zg-height="360"></div>
    ...
    <script src="./zego-express-engine-webrtc/ZegoExpressWebRTC-3.0.0.js"></script>
    <script src="./zego-express-player/ZegoExpressPlayer-1.3.0.js"></script>
</body>
</html>

...
<body>
    ...
    <div id="player-container" zg-width="640" zg-height="360"></div>
    ...
    <script src="./zego-express-engine-webrtc/ZegoExpressWebRTC-3.0.0.js"></script>
    <script src="./zego-express-player/ZegoExpressPlayer-1.3.0.js"></script>
</body>
</html>

Instantiate Player Plugin and Authenticate

After importing the Player Plugin package with the <script> tag, the prototype of ZegoExpressPlayer will be mounted on the global object of the current runtime environment. You can instantiate the Player Plugin in a JS file.
Initialize the Player and perform Authentication. Otherwise, you cannot continue to use other interfaces of the Player.

Warning

If you have successfully logged into the Room through the Express Web SDK's loginRoom interface, you do not need to authenticate the Player Plugin again here.
If you have not used the Express Web SDK's loginRoom interface to log into the Room, you must authenticate the Player Plugin here. For the method of obtaining Token, please refer to Using Token Authentication.

...
const zg = new ZegoExpressEngine(...);

const player = new ZegoExpressPlayer(zg, {
  container: document.getElementById("player-container"),
  mode: "live"
});
...
const res = await player.verify(token, userID); // Player authentication, returns true / false, representing authentication success and failure respectively.

...
const zg = new ZegoExpressEngine(...);

const player = new ZegoExpressPlayer(zg, {
  container: document.getElementById("player-container"),
  mode: "live"
});
...
const res = await player.verify(token, userID); // Player authentication, returns true / false, representing authentication success and failure respectively.

Use Player Plugin to Request Resources and Start Playing

Call the Player instance interface to control the Player state and receive callback notifications from the Player. You can play CDN live streams by setting the URL address.

Warning

Currently, this Player Plugin only supports the FLV protocol.

player.onError = (err) => {
    console.error(err);
    if (err.code === 100006) {
        // Handle autoplay failure. If you need on-screen autoplay, this error may be triggered due to browser restrictions. Guide the user to click and then call player.play();
    }
}
player.src = "http://xxxx/livestream/stream.flv"; // Currently only supports http-flv format resources
player.play();
...

player.onError = (err) => {
    console.error(err);
    if (err.code === 100006) {
        // Handle autoplay failure. If you need on-screen autoplay, this error may be triggered due to browser restrictions. Guide the user to click and then call player.play();
    }
}
player.src = "http://xxxx/livestream/stream.flv"; // Currently only supports http-flv format resources
player.play();
...

More Features

The Player Plugin also supports: pausing or interrupting resource requests, fullscreen display, Stream Playing SEI callback, media information callback, and other features. For more feature descriptions, please refer to the API interface documentation of ZegoExpressPlayer.

Complete Example Code

We provide a complete example code for integrating the Player Plugin as a reference during the development process.

Complete Example Code for Integrating Player Plugin

Use a static service such as 'http-server' to open the demo for testing. Do not open the demo.html file directly from the browser.

The following is an example code for the demo.html file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Zego Express Player Demo</title>
    <style>
        #modal {
          display: none;
          position: fixed;
          left: 0;
          top: 0;
          width: 100%;
          height: 100%;
          background-color: rgba(0, 0, 0, 0.5);
          z-index: 9999;
        }

        #modal-content {
          background-color: #fff;
          width: 300px;
          padding: 20px;
          position: absolute;
          top: 50%;
          left: 50%;
          transform: translate(-50%, -50%);
        }

        #modal-buttons {
          text-align: center;
        }
      </style>
</head>
<body>
    <div id="player-container" zg-width="640"></div>

    <button id="load-play-btn">Load Resource and Play</button>

    <div id="modal">
        <div id="modal-content">
            <p>Autoplay failed. After you confirm, the video will continue to play.</p>
                <div id="modal-buttons">
                    <button id="confirm-btn">Confirm</button>
                </div>
        </div>
    </div>

    <script src="./zego-express-engine-webrtc/ZegoExpressWebRTC-3.0.0.js"></script>
    <script src="./zego-express-player/ZegoExpressPlayer-1.3.0.js"></script>
    <script>
        function closeModal() {
            var modal = document.getElementById('modal');
            modal.style.display = 'none';
        }

        function openModal() {
            closeModal();
            var modal = document.getElementById('modal');
            modal.style.display = 'block';
        }

        window.onload = async () => {
            // This test DEMO requires you to configure the following parameters to use:
            const   appID = 0,
                    server = "",
                    userID = "",
                    token = "";

            const zg = new ZegoExpressEngine(appID, server);

            try {
                const player = new ZegoExpressPlayer(zg, {
                    container: document.getElementById("player-container"),
                    mode: "live"
                });

                const res = await player.verify(token, userID); // Note: The authentication interface here is asynchronous. You need to wait for the asynchronous authentication to complete before continuing to call other Player interfaces.

                if (!res) {
                    console.error("Player authentication failed!");
                }

                document.getElementById("confirm-btn").onclick = ()=>{
                    player.play();
                    closeModal();
                }

                player.onError = (err) => {
                    console.error(err);
                    if (err.code === 100006) {
                        // Handle autoplay failure, guide the user to click and then call player.play();
                        openModal();
                    }
                }

                player.onWaiting = () => {
                    console.warn("media waiting..");
                }

                player.onPlaying = () => {
                    console.warn("media playing..");
                }

                player.onEnded = () => {
                    console.warn("meida play ended.");
                }

                player.onCanPlay = () => {
                    console.warn("meida play can play.");
                }

                player.onPlay = () => {
                    console.warn("meida played.");
                }

                player.onPaused = () => {
                    console.warn("meida paused.");
                }

                player.onLoaded = () => {
                    console.warn("meida loaded.");
                }

                player.onTimeUpdate = () => {
                    // console.warn("currentTime: ", player.currentTime);
                }

                player.onMediaInfoUpdate = (mediainfo) => {
                    console.warn("media info update: ", JSON.stringify(mediainfo, null, 2));
                }

                player.onRecvSEI = (data) => {
                  console.warn(data);
                }

                document.addEventListener("click", () => {
                    player.src = "";
                    player.play();
                });
            } catch (err) {
                console.error(err);
            }

        }
    </script>
</body>
</html>

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Zego Express Player Demo</title>
    <style>
        #modal {
          display: none;
          position: fixed;
          left: 0;
          top: 0;
          width: 100%;
          height: 100%;
          background-color: rgba(0, 0, 0, 0.5);
          z-index: 9999;
        }

        #modal-content {
          background-color: #fff;
          width: 300px;
          padding: 20px;
          position: absolute;
          top: 50%;
          left: 50%;
          transform: translate(-50%, -50%);
        }

        #modal-buttons {
          text-align: center;
        }
      </style>
</head>
<body>
    <div id="player-container" zg-width="640"></div>

    <button id="load-play-btn">Load Resource and Play</button>

    <div id="modal">
        <div id="modal-content">
            <p>Autoplay failed. After you confirm, the video will continue to play.</p>
                <div id="modal-buttons">
                    <button id="confirm-btn">Confirm</button>
                </div>
        </div>
    </div>

    <script src="./zego-express-engine-webrtc/ZegoExpressWebRTC-3.0.0.js"></script>
    <script src="./zego-express-player/ZegoExpressPlayer-1.3.0.js"></script>
    <script>
        function closeModal() {
            var modal = document.getElementById('modal');
            modal.style.display = 'none';
        }

        function openModal() {
            closeModal();
            var modal = document.getElementById('modal');
            modal.style.display = 'block';
        }

        window.onload = async () => {
            // This test DEMO requires you to configure the following parameters to use:
            const   appID = 0,
                    server = "",
                    userID = "",
                    token = "";

            const zg = new ZegoExpressEngine(appID, server);

            try {
                const player = new ZegoExpressPlayer(zg, {
                    container: document.getElementById("player-container"),
                    mode: "live"
                });

                const res = await player.verify(token, userID); // Note: The authentication interface here is asynchronous. You need to wait for the asynchronous authentication to complete before continuing to call other Player interfaces.

                if (!res) {
                    console.error("Player authentication failed!");
                }

                document.getElementById("confirm-btn").onclick = ()=>{
                    player.play();
                    closeModal();
                }

                player.onError = (err) => {
                    console.error(err);
                    if (err.code === 100006) {
                        // Handle autoplay failure, guide the user to click and then call player.play();
                        openModal();
                    }
                }

                player.onWaiting = () => {
                    console.warn("media waiting..");
                }

                player.onPlaying = () => {
                    console.warn("media playing..");
                }

                player.onEnded = () => {
                    console.warn("meida play ended.");
                }

                player.onCanPlay = () => {
                    console.warn("meida play can play.");
                }

                player.onPlay = () => {
                    console.warn("meida played.");
                }

                player.onPaused = () => {
                    console.warn("meida paused.");
                }

                player.onLoaded = () => {
                    console.warn("meida loaded.");
                }

                player.onTimeUpdate = () => {
                    // console.warn("currentTime: ", player.currentTime);
                }

                player.onMediaInfoUpdate = (mediainfo) => {
                    console.warn("media info update: ", JSON.stringify(mediainfo, null, 2));
                }

                player.onRecvSEI = (data) => {
                  console.warn(data);
                }

                document.addEventListener("click", () => {
                    player.src = "";
                    player.play();
                });
            } catch (err) {
                console.error(err);
            }

        }
    </script>
</body>
</html>