Appearance

观看端SDK接入 ​

开发前准备 ​

SDK需要依赖商家C端用户sdkToken凭证才能运行，token获取示例如下（示例代码仅用于测试使用，线上业务需要商家后端封装、后端封装、后端封装，避免secret_key泄露）

client_id和secret_key在云服务控制台获取

sdkToken生成示例 ​

关键参数 ​
字段类型必填说明示例
sdk_app_idstring是商家的应用IDxopCt3TZuko5025
sdk_user_idstring是商家侧用户唯一标识sdk_test_user_001
expireint是Token到期时间（秒级时间戳），根据实际使用场景设置，建议不要太长1736393420
代码示例 ​

Golang

安装依赖：go get github.com/golang-jwt/jwt/v5

Golang
import (
	"github.com/golang-jwt/jwt/v5"
	"time"
)

// GetSDKToken 生成token
func GetSDKToken(sdkAppId string, sdkSecret string, sdkUserId string) (string, error) {
	claims := jwt.MapClaims{
		"sdk_app_id":  sdkAppId,                              //小鹅云client_id
		"sdk_user_id": sdkUserId,                             //商家用户id
		"expire":      time.Now().Add(time.Hour * 24).Unix(), // sdkToken到期时间（单位：秒，24小时后）
	}
	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
	return token.SignedString([]byte(sdkSecret))
}

JavaScript

安装依赖：npm install jsonwebtoken

JavaScript
const jwt = require('jsonwebtoken');

/**
 * 生成 token
 * @param {string} sdkAppId - 小鹅云 client_id
 * @param {string} sdkSecret - 小鹅云 client_secret
 * @param {string} sdkUserId - 商家用户 id
 * @returns {string} 生成的 token
 */
function getSDKToken(sdkAppId, sdkSecret, sdkUserId) {
  // 定义 claims
  const claims = {
    sdk_app_id: sdkAppId, // 小鹅云 client_id
    sdk_user_id: sdkUserId, // 商家用户 id
    expire: Math.floor(Date.now() / 1000) + 24 * 60 * 60 // sdkToken到期时间（单位：秒，24小时后）
  };

  // 使用 HS256 算法生成 token
  return jwt.sign(claims, sdkSecret, { algorithm: 'HS256' });
}

PHP

安装依赖：composer require firebase/php-jwt

PHP
use Firebase\JWT\JWT;
use Firebase\JWT\Key;

require 'vendor/autoload.php';

/**
 * 生成 token
 *
 * @param string $sdkAppId  小鹅云 client_id
 * @param string $sdkSecret 令牌签名密钥
 * @param string $sdkUserId 商家用户 ID
 * @return string
 */
function getSDKToken(string $sdkAppId, string $sdkSecret, string $sdkUserId): string {
    $claims = [
        "sdk_app_id"  => $sdkAppId, //小鹅云client_id
        "sdk_user_id" => $sdkUserId, // 商家用户 id
        "expire"      => time() + 24 * 60 * 60 // sdkToken到期时间（单位：秒，24小时后）
    ];

    return JWT::encode($claims, $sdkSecret, 'HS256');
}

H5SDK接入 ​

客户使用只需要调整下图中的直播间初始化逻辑，基于开发前准备好的sdkToken

初始化直播间字段说明：

字段说明是否必填示例
liveId直播间id是l_677f2c7be4b023c058c576eb
appId小鹅通店铺id是app4duupn5j6765
sdkAppId小鹅云开放平台client_id是xop91owbHx29017
sdkTokensdk请求凭证是eyJhbGciOiJIcCI6IkpXVCJ9.eyJleHBpcmUiOjE3UiLCJzZGtfdXNlcl9pZCI6InXzAwMSJ9.dOcxQ-bg7_k3uCsH2vIqifsdIa-Jh15SWPA
userId商家用户id是test_1
nickname商家用户昵称否测试用户1
avatar商家用户头像否https://www.touxiang.com/xxx.jpg

小程序SDK接入 ​

注意：需要工程执行yarn命令（node版本 >16），客户工程主包需要预留400kb左右

  1. 拷贝目录： minirprogram_npm、packag-watch、package-watch-business、package-watch-room、package-watch-sdk、app.json

  2. app.js 定义全局变量

  3. 初始化直播间示例

  4. 微信接口白名单配置，请商家在自有微信小程序开发者平台添加

#request合法域名
https://api.xiaoeknow.com
https://liveplay-byte.xiaoeknow.com
https://liveplay.xiaoeknow.com
https://liveplay-hw-hls.xiaoeknow.com
https://alivereport.xiaoeknow.com
https://learnreport.xiaoeknow.com
https://logreport.xiaoeknow.com
https://sensitive.xiaoeknow.com

#socket合法域名
wss://wss.im.qcloud.com

移动端SDK接入 ​

iOS ​

  1. 解压xelivescenessdk-ios-demo_vxx.xx.xx.zip交付产物；

  2. 将XELiveScenesSDKDemo/SDK目录拷贝到自己的APP工程里，并设置APP工程的Build Settings/Other Linker Flags增加配置**-ObjC** 、 -all_load ；

  3. 参考Demo相关接入流程按需对接SDK功能；

  4. Demo运行：点击XELiveScenesSDKDemo.xcworkspace文件，将Demo工程的Signing & Capabilities中的包ID信息**（Bundle Indentifier）** 及开发者证书信息**（ Provisioning Profile）**修改成自己能用于真机打包测试的开发信息，即可直接运行起Demo到真机测试；

  5. H5二次开发：可直接根据小鹅通提供的本地H5开发规范按需修改相关功能，修改的本地H5资源文件默认存放于：XELiveScenesSDKDemo/SDK/XELiveScenesSDK.bundle/web目录下；

  6. H5加载参考代码：[self.liveH5View loadH5Link:[NSString stringWithFormat:@"/live/index.html?alive_id=%@&app_id=%@",self.liveId,self.appId]];

  7. APP初始化SDK参考代码

  8. APP接入SDK支持配置自定义的H5资源存放根目录，可通过二次开发自研扩展本地H5热更新能力，设置属性

本地网页存放的根目录 ，默认 \[NSBundle mainBundle\].resourcePath + \"/XELiveScenesSDK.bundle/web\"

**\@property** (**nonatomic**,**strong**) NSString \*webRootDir;
  1. APP接入SDK提供的本地H5加载容器类XELiveWebView接入代码实现参考:XELLiveWebViewController；
  2. 网页画中画PiP服务依赖辅助类：XELLiveWebClient ；

Android ​

  1. 获取aar交付产物
  2. 添加gradle依赖implementation(files(\"libs/xiaoe-live-scenes-sdk-release-v1.0.0.17.aar\"))
  3. 在加载直播间的activity或者fragment的布局内新增一个layout用来承载webview
  4. 在activity内初始化XELiveScenesWeb
  5. 配置webview的生命周期依赖
Kotlin
@RequiresApi(Build.VERSION_CODES.O)
override fun onResume() {
    super.onResume()
    mWeb?.onResume()
}

@RequiresApi(Build.VERSION_CODES.O)
override fun onPause() {
    super.onPause()
    mWeb?.onPause()
}

@RequiresApi(Build.VERSION_CODES.O)
override fun onDestroy() {
    super.onDestroy()
    mWeb?.onDestroy()
    mWeb = null
}
  1. 如果需要画中画能力，需要增加以下几项配置
  • 增加画中画支持和屏幕变化配置
XML
<activity android:name=".XiaoeLiveSdkActivity"
    android:exported="true"
    android:supportsPictureInPicture="true"
    android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation">
</activity>
  • 实现画中画模式变化监听
Kotlin
@RequiresApi(Build.VERSION_CODES.O)
override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean, newConfig: Configuration?) {
    super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
    mWeb?.onPipModeChanged(isInPictureInPictureMode)
}
  • 如果需要实现切后台自动画中画能力，需要额外增加如下实现
Kotlin
@RequiresApi(Build.VERSION_CODES.O)
override fun onUserLeaveHint() {
    super.onUserLeaveHint()
    mWeb?.enterPip()
}
  1. 离线H5说明
  • 离线H5支持二次开发
  • 目前支持将二次开发后的H5打包放到assets目录下或者手机存储内，具体差异参考demo的实现

Harmony ​

接入流程 ​
  1. HAR 包接入方式
  • SDK 以 HAR 包形式交付，har包可以在下面交付产物获取。
  • 引入后确保工程可识别与编译通过。
  1. 添加包依赖（本地 file 依赖） 在业务模块的 oh-package.json5 中添加依赖：
js
{
  "dependencies": {
    "@xiaoe/live_scenes": "file:../live_scenes.har"
  }
}
  1. 权限申请 至少申请以下权限：
 ohos.permission.INTERNET（网络访问）
 ohos.permission.PRIVACY_WINDOW（隐私窗口能力）
  1. 动态更新配置 初始化后可在运行时更新部分配置：
ts
XELiveSDK.updateConfig({
  showLog: false,
  backgroundAutoPipAccess: true,
})

注意：首次 init 仍然是必要的，updateConfig 仅用于运行时调整。

快速接入 ​
  1. 初始化 在 EntryAbility.onWindowStageCreate 的 loadContent 回调中调用初始化：
ts
onWindowStageCreate(windowStage: window.WindowStage) {
  windowStage.loadContent('pages/Live', () => {
    XELiveSDK.init({
      showLog: true,
      baseUrl: 'resource://resfile',
      context: windowStage.getMainWindowSync().getUIContext(),
      antiScreenCaptureAccess: false,
      backgroundAutoPipAccess: false,
    })
  })
}

必要参数：showLog、baseUrl、context；其余按业务需要配置。

  1. 构建节点并获取控制器 最小可运行示例：
ts
import { XEWebNodeBuilder, XELiveWebController } from '@xiaoe/live_scenes'

const nodeObj = new XEWebNodeBuilder()
  .withPath(path)//index.html?alive_id=l_6837d108e4b0694ca0bb5008&app_id=appmmmzngny9263
  .withController(new MyController())
  .withEventDelegate(new MyEventDelegate())
  .withWebOption(new MyWebOptions())
  .build()

const controller = nodeObj.controller as XELiveWebController
  • eventDelegate：继承于 XeWebEventClient 的实例，基于系统 Web 组件，供业务方使用
  • controller：继承于 XELiveWebController 的实例，提供 JS 回调事件、返回、进入小窗，退出等功能
  • webOption：配置Web组件的属性
  • Path：配置path参数，无需Host
  1. PiP 操作与回调 进入/退出 PiP 以及绑定回调：
ts
controller.enterPip()
controller.outPip()

controller.addPipCallback({
  onAboutToStart: () => {},
  onStoppedRestore: () => {},
  onStoppedClose: () => {},
  onAboutToRestore: () => {},
  onError: () => {},
})
  1. 管理器模式（Demo 参考 - 可选） XELiveManager 为 Demo 封装（缓存复用、导航协调），非 SDK 必需，具体实现参考demo：
ts
const nodeObj = XELiveWebManager.obtainWebViewLiveWeb(url)
const controller = XELiveWebManager.getController(url) as MyController
  1. 节点容器渲染 当不处于 PiP 时，将当前 XEWebNode 渲染到 NodeContainer:
ts
import { XEWebNode } from "@xiaoe/live_scenes";
import { XELiveWebManager } from "../manager/XELiveManager";

@ComponentV2
export struct XELiveWeb {
  @Local node?: XEWebNode

  aboutToAppear(): void {
    this.node = XELiveWebManager.getNode()
  }

  build() {
    if (!XELiveWebManager.isPip) {
      NodeContainer(this.node)
        .layoutWeight(1)
        .onAppear(() => {
        })
    }
  }
}