Web SDK 使用指南

Web 端可以通过 Web SDK 接入，也可直连接入。Web SDK 接入与直连接入的区别：

	Web SDK 接入	Web 直连接入
接入便捷性	便捷	最便捷
HTTPS	网站需配置 HTTPS	网站无需配置 HTTPS
高级功能	直播间嵌入商品、邀请排行榜等	无

TIP

如无特殊需求，建议使用 Web 直连接入 。

Web 直连接入

直连接入，即给用户生成一个直播课堂的进入地址，浏览器直接重定向到该地址，即可进入直播课堂。

直播进入地址规则：

https://live.edusoho.com/h5/room/{roomId}/enter?token={token}

回放进入地址规则：

https://live.edusoho.com/h5/replay/{roomId}/enter?token={token}

参数说明：

名称	类型	描述
`roomId`	integer	直播课堂ID
`token`	string	鉴权 Token，见文末
`inapp` 可选	integer	默认为 `0`；当页面嵌入 App 的 WebView 时，请设置为 `1`

Web SDK 接入

STEP 1: 引入 SDK

如果你项目中使用NPM或YARN包管理器，那么使用以下命令安装：

npm i @edusoho-live/eslive-web-sdk

yarn add @edusoho-live/eslive-web-sdk

也可以直接下载 SDK 文件，放到你的项目的 JS 目录下，下载地址： https://unpkg.com/@edusoho-live/eslive-web-sdk@latestopen in new window

STEP 2: 编辑 HTML 页面

添加：

<div id="eslive-container" 
  style="position: absolute;left: 0;right: 0;top: 0;bottom: 0;"></div>

给 <body> 元素，添加以下样式，以禁止浏览器的回弹效果：

<body style="width: 100%;height: 100%;overflow: hidden;">

在<head>节点下添加：

<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,minimum-scale=1,viewport-fit=cover,user-scalable=no">

STEP 3: 调用 SDK

import ESLiveWebSDK from '@edusoho-live/eslive-web-sdk';

// 直播课堂进入地址，通过调用业务服务器程序接口获取
const params = {
  url: "https://live.edusoho.com/h5/room/.../enter?token=..."
}

async function initSDK(params) {
    const sdk = new ESLiveWebSDK();
    await sdk.connect({
        container: "eslive-container",
        url: params.url,
        watermark: "watermark-test",
    })
}
initSDK();

参数说明：

名称	类型	描述
`container`	integer	即页面中 ID 为 eslive-container 的 div 容器
`url`	string	完整的直播/回放进入链接
`watermark` 可选	string	水印文字
`floatButtons` 可选	FloatButton[]	直播间悬浮按钮，如商品购买

interface FloatButton {
    /**
     * 浮动按钮编码，系统预制的编码有： goods (商品购买)
     */
    code: string;
    /**
     * 浮动按钮图标，不填则使用默认图标
     */
    icon?: string;
    /**
     * 浮动按钮标题，不填则为默认标题
     */
    name?: string;
    /**
     * 内容数据，商品列表应传 `goods: SDKGoods[]`
     */
    [key: string]: unknown;
}
/**
 * 商品参数
 */
interface SDKGoods {
    no: string;           // 商品编号
    name: string;         // 商品名称
    price: number;        // 商品价格
    picture: string;      // 商品图片
    description: string;  // 商品描述
    paid: boolean;        // 商品是否已购买
    goto: boolean;        // 商品详情跳转链接
}

SDK 接口

`play()`

开始播放，此接口只针对回放有效。

浏览器为了防止网页在用户非自愿的情况下主动播放声音，对网页上的自动播放（Autoplay）功能做了限制：浏览器在没有用户交互操作（点击、触摸等）之前不允许有声音的媒体播放。这个限制是出于用户体验的考虑，因为通常情况下用户访问网页后突然自动播放音频可能是违背用户意愿的。所以此接口需在点击/触摸事件中调用。

使用示例：

sdk.play();

`pause()`

暂停播放，此接口只针对回放有效。

使用示例：

sdk.pause();

`notify()`

事件接口。

使用示例：

// 商品购买完成后的通知
sdk.notify('Goods.Paid', {no: 'xxxx', goto: 'https://xxxx'});

SDK 事件

`LiveStart`

直播课堂开始上课。课堂处于上课状态，每次重新进入课堂，也都会抛出此事件。

sdk.on("LiveStart", () => {...});

`LiveFinished`

直播课堂下课。

sdk.on("LiveFinished", () => {...});

`Watching`

直播/回放观看状态事件，只有音视频流在播放时才会抛出此事件，每秒抛出1次。当老师离开课堂、网络缓冲、用户手动暂停时，暂停抛出此事件。

// 在使用倍数观看回放时，参数 rate 为相应的倍数；直播时，参数 rate 为 1。
sdk.on('Watching', (rate) => {...});

`Goods.Buy`

直播间商品购买事件。

sdk.on('Goods.Buy', (goodsNo) => {...});

`Goods.Goto`

直播间商品详情跳转事件。

sdk.on('Goods.Goto', (goodsNo) => {...});

生成 Token

使用 JWTopen in new window 生成 Token。

注意

出于安全考虑，此 Token 必须由服务端生成！

JWT Header:

{
  "kid": "testAccessKey",
  "typ": "JWT",
  "alg": "HS256"
}

kid 即云平台账号的 AccessKey。

JWT Payload:

{
  "rid": 69004,
  "uid": 515775872265224,
  "name": "韩梅梅",
  "role": "speaker",
  "iss": "live client api",
  "exp": 1597137128
}

名称	类型	描述
`rid`	integer	直播课堂 ID
`uid`	integer	用户 ID，须为整形数
`name`	string	用户昵称
`role`	enum	用户角色(`speaker`: 主播，`viewer`: 观众，助教: `assistant`)
`iss`	string	JWT 签发者，该值固定为 `live client api`
`exp`	integer	JWT 过期时间戳(秒)，建议设置为`直播间结束时间`，以免 Token 过期，导致无法进入直播课堂

JWT Signature:

使用云平台账号 SecretKey 和 HS256 算法签名。

生成 Token 的 Java 示例

Java 程序，可以通过调用 SDK 方法生成，也可以自行生成 Token。其他语言开发的程序，可参照 Java 示例代码，自行生成 Token。

方式一：通过调用 SDK 生成

Maven 引入eslive-api-java-sdk包：

<dependency>
    <groupId>com.edusoho.live</groupId>
    <artifactId>eslive-api-java-sdk</artifactId>
    <version>1.0.2</version>
</dependency>

可在 https://mvnrepository.com/artifact/com.edusoho.live/eslive-api-java-sdkopen in new window 查看最新的 SDK 版本。

示例：

import com.edusoho.live.sdk.ClientConfig;
import com.edusoho.live.sdk.EsliveApiClient;
import com.edusoho.live.sdk.model.Role;

ClientConfig config = new ClientConfig();
config.setAccessKey("<your access key>");
config.setSecretKey("< your secret key>");

EsliveApiClient client =  new EsliveApiClient(config);

// 这里生成的是带 Token 的进入直播课堂的 URL 地址，可在浏览器中打开，或作为参数传递给客户端 SDK
String roomUrl = client.roomGetEnterUrl(1000L, 1L, "韩梅梅", Role.VIEWER);

// 这里生成的是带 Token 的进入直播回放的 URL 地址，可在浏览器中打开，或作为参数传递给客户端 SDK
String replayUrl = client.replayGetEnterUrl(1000L, 1L, "韩梅梅", Role.VIEWER);

方式二：自行生成

Maven 引入java-jwt包：

<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>java-jwt</artifactId>
    <version>3.19.2</version>
</dependency>

在这里 https://mvnrepository.com/artifact/com.auth0/java-jwtopen in new window 可以查询到 jata-jwt 的最新版本。

示例：

import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;

 String token = JWT.create()
                .withKeyId("<your access key>")
                .withIssuer("live client api") // 签发者，固定为 live client api
                .withClaim("rid", 1000L) // 直播课堂ID
                .withClaim("uid", 1L) // 用户ID
                .withClaim("name","韩梅梅") // 用户名
                .withClaim("role", "viewer") // 角色
                .withExpiresAt(1654833983) //设置为直播课堂结束的时间戳，单位为秒
                .sign(Algorithm.HMAC256("<your secret key>"));

Token 按照生成课堂进入地址文档中所描述的规则，拼接 URL，即可进入直播或回放。

# Web SDK 使用指南

# Web 直连接入

# Web SDK 接入

# SDK 接口

# play()

# pause()

# notify()

# SDK 事件

# LiveStart

# LiveFinished

# Watching

# Goods.Buy

# Goods.Goto

# 生成 Token

# 生成 Token 的 Java 示例

# 方式一：通过调用 SDK 生成

# 方式二：自行生成

Web SDK 使用指南

Web 直连接入

Web SDK 接入

SDK 接口

`play()`

`pause()`

`notify()`

SDK 事件

`LiveStart`

`LiveFinished`

`Watching`

`Goods.Buy`

`Goods.Goto`

生成 Token

生成 Token 的 Java 示例

方式一：通过调用 SDK 生成

方式二：自行生成