文档中心

企业直播

WebView SDK

集成 WebView SDK

企业直播 WebView SDK 是面向原生 App 的集成 SDK。它以企业直播 H5 页面和 Web 观播 SDK 为内容载体，通过封装 WebView 容器，为开发者提供页面生命周期管理、小窗与 PiP 控制、宿主与 H5 通信等能力，帮助您快速集成企业直播观看体验。本文将分别介绍如何在 uni-app、Android 和 iOS 项目中接入和使用企业直播 WebView SDK。

适用场景

如果您希望将企业直播能力嵌入 Android、iOS 或 uni-app 宿主 App 中，并与 App 的原生能力进行联动，可以选择 WebView SDK。
WebView SDK 适用于以下场景：

已拥有 Android、iOS 或 uni-app 宿主 App，需要在 App 内集成企业直播观看页。
希望观播页面与 App 的导航栏、返回逻辑、安全区、小窗等交互保持一致。
需要支持应用内小窗（PiP）等多任务观看体验。
需要通过宿主 App 提供分享、支付、下载、路由跳转等原生能力。
需要实现宿主与观播页面之间的双向通信和状态同步。

如果您希望直接在浏览器中访问直播页面，或仅需在 Web 页面中集成直播能力，则建议使用集成 Web 观播 SDK。

核心能力

企业直播 WebView SDK 提供以下核心能力：

小窗与 PiP：支持应用内小窗播放，可配置小窗位置、尺寸、允许进入小窗的直播间状态，以及下拉刷新、侧滑返回等手势能力。部分场景下，小窗可展示签到、抽奖等直播互动信息，方便用户快速返回直播间。
全屏播放与页面联动：支持全屏播放模式，并与宿主 App 的导航栏、安全区、返回逻辑等页面元素联动。宿主可根据业务需求控制导航栏显隐、页面布局及横屏体验。
宿主与 H5 通信：提供宿主与观播页面之间的双向通信机制。宿主可以监听直播 WebView 事件，也可以通过 notifyWebview() 将事件和业务数据发送给 H5 页面。
原生能力扩展：支持观播页面通过桥接机制向宿主 App 发起 Native API 请求。Android/iOS SDK 负责透传请求和回调结果，分享、支付、文件下载、图片保存、路由跳转、本地存储等具体能力由宿主按业务实现；uni-app 适配层内置了部分常用 API 代理。
播放体验优化：针对直播场景优化 WebView 集成体验，支持页面切换、小窗切换等场景下的播放控制与状态管理。

| | | | | \

能力	uni-app	Android	iOS

应用内小窗	✅	✅	✅

系统画中画 (PiP)	✅ (Android 8.0+)	✅ (Android 8.0+)	✅ (iOS 12+)

全屏播放	✅	✅	✅

宿主与 H5 通信	✅	✅	✅

原生能力扩展	✅ (内置部分 API 代理)	✅ (宿主实现)	✅ (宿主实现)

下拉刷新	✅	✅ (宿主实现)	✅ (宿主实现)

侧滑返回	✅	✅ (宿主实现)	✅ (宿主实现)

uni-app 接入

uni-app SDK 以 DCloud 本地原生插件形式交付，包含 Android 和 iOS 原生能力封装，以及适用于 uni-app 的 JS 调用层。您可以通过 uni_modules/byte-live-player 调用 SDK 提供的 JS 接口，底层通过 nativeplugins/byteLivePlayer 接入 Android 和 iOS 原生能力。SDK 包同时包含 Android AAR、iOS Framework 以及 uni_modules 相关代码，您可直接集成至 uni-app 工程中使用。

环境要求

仅支持 uni-app App-Plus 运行环境，需要使用包含 byteLivePlayer 原生插件的自定义调试基座、离线打包工程或云打包产物；标准基座不包含该插件。
Android 端要求 Android 5.0（API Level 21）及以上版本。系统级画中画（PiP）功能依赖 Android 8.0（API Level 26）及以上版本；低版本设备仍可使用应用内小窗能力。
iOS 端要求 iOS 12.0 及以上版本。iOS 插件会自动合并运行所需的系统 Framework、权限声明及相关配置，开发者无需手动添加。
如需在 iOS 模拟器中进行调试，请使用包含 Simulator Slice 的自定义基座或 .xcframework 产物。真机基座与模拟器基座不兼容，不能混用。

步骤一：下载 SDK 集成包

点击下载 SDK 集成包：

集成包目录如下所示：

byte-live-player-delivery-<version>
├── nativeplugins
│   └── byteLivePlayer
│       ├── android
│       │   └── ByteLivePlayer.aar
│       ├── ios
│       │   └── ByteLivePlayer.framework
│       └── package.json
└── uni_modules
    └── byte-live-player

解压 SDK 包，将 nativeplugins/byteLivePlayer 和 uni_modules/byte-live-player 分别拷贝到 uni-app 工程的同名目录下。
（可选）如果您的 uni-app 工程使用 npm / Vite / Vue CLI 等模块化构建方式，建议在 package.json 中添加本地依赖，以便构建系统正确识别 SDK 模块：
```
{
  "dependencies": {
    "@byte-live/live-player": "file:uni_modules/byte-live-player"
  }
}
```
添加后请重新执行依赖安装（如 npm install 或 pnpm install）。

步骤二：启用原生插件

在使用 SDK 前，需要在 uni-app 工程中启用原生插件 byteLivePlayer，否则运行时将无法调用相关能力。

您可通过以下两种方式启用：

方式一：通过 HBuilderX 启用：在 HBuilderX 中打开 manifest.json，进入 App 原生插件配置页，勾选 byteLivePlayer 插件并保存。

方式二：如果使用手动编辑 manifest.json，请在 app-plus.nativePlugins 中添加如下配置：

{
    "app-plus": {
        "nativePlugins": {
            "byteLivePlayer": {
                "__plugin_info__": {
                    "name": "byteLivePlayer",
                    "description": "ByteLivePlayer: PiP, autoplay, etc (Android/iOS)",
                    "platforms": "Android,iOS",
                    "isCloud": false
                }
            }
        }
    }
}

修改原生插件配置后，需要重新制作并安装包含该插件的自定义调试基座，或重新执行云打包或离线打包应用，否则插件不会生效。在代码中，可通过以下代码验证插件是否已生效：
```
const byteLivePlayer = uni.requireNativePlugin('byteLivePlayer');
if (!byteLivePlayer) {
  // 当前基座未包含 byteLivePlayer，需重新制作自定义基座或检查 nativeplugins 目录与 manifest 配置。
}
```

步骤三：打开 WebView 页面

本小节介绍打开 WebView 页面的两种方式。

方式一：通过 `LivePlayerManager` 打开观播页面

SDK 提供默认的 LivePlayerManager 单例，用于创建和管理直播页面。引入 SDK 后，您可以通过 LivePlayerManager.open() 打开直播页面。示例代码如下所示。参数说明请参考下文。

import LivePlayerManager from '@byte-live/live-player';

LivePlayerManager.open('https://example.com/live', {
  contentPlayerWebViewId: 'live-room-xxx',  // 当前直播页面实例的唯一标识。必填。
  title: '直播',
  fullscreen: false,
  keepSafeTop: false,
  pipStyles: {
    enableInAppPiP: true,
    enableSystemPiP: true,
    pipSize: { ratio: 0.45 },
    allowedRoomStatuses: [1, 2, 3]
  },
  enablePullRefresh: true,
  enableSwipeBack: true
});

方式二：通过 `LivePlayer` 组件集成直播能力

如果希望以组件形式在页面中集成观播能力，也可以使用 LivePlayer 组件。多个组件实例之间相互独立，可分别进行生命周期管理。示例代码如下所示。参数说明请参考下文。

<template>
  <LivePlayer
    src="https://example.com/live"
    content-player-web-view-id="live-room-xxx"
    :pip-styles="pipStyles"
    @message="onMessage"
    @exit-web-view="onExitWebView"
  />
</template>

<script>
import { LivePlayer } from '@byte-live/live-player';

export default {
  components: { LivePlayer },
  data() {
    return {
      pipStyles: {
        enableInAppPiP: true,
        enableSystemPiP: true,
        pipSize: { ratio: 0.45 },
        allowedRoomStatuses: [1, 2, 3]
      }
    };
  },
  methods: {
    onMessage(event) {
      // event.detail.data 与 uni-app web-view message 形态对齐。
    },
    onExitWebView() {
      // 用户或 H5 触发退出播放。
    }
  }
};
</script>

参数说明
打开观播页面的参数说明如下所示。详情参考WebView SDK API 参考。

| | | | | | \

参数	类型	是否必填	默认值	说明

url	string	是	无	观播页面地址。

				* 通过 `LivePlayerManager` 打开直播页面场景下，使用 `open(url, options)`；
				* 通过 `LivePlayer` 组件场景下，使用 `src` 或 `url`。

contentPlayerWebViewId	\
	string	是	无	\
				当前观播页面实例的唯一标识。您需使用唯一字符串，例如直播间 ID 或播放器实例 ID。不同直播页面实例应使用不同的值。该标识用于直播页面的创建、恢复、小窗展示和系统画中画等场景。请勿直接使用 `plus.webview.currentWebview().id` 作为 `contentPlayerWebViewId`。

title	string	否	无	观播页面标题。部分场景下可用于导航栏标题展示。仅在通过 `LivePlayerManager` 打开直播页面场景有效。

fullscreen	boolean	否	true	是否以全屏模式展示观播页面。仅在通过 `LivePlayerManager` 打开直播页面场景有效。

keepSafeTop	boolean	否	true	是否保留顶部安全区域。开启后，观播页面内容不会覆盖状态栏区域。仅在通过 `LivePlayerManager` 打开直播页面场景有效。

pipStyles	object	否	无	小窗及系统画中画相关配置。

pipStyles.enableInAppPiP	boolean	否	true	是否启用应用内小窗能力。

pipStyles.enableSystemPiP	boolean	否	false	是否启用系统画中画（PiP）能力。Android 端系统级画中画（PiP）功能依赖 Android 8.0（API Level 26）及以上版本；低版本设备仍可使用应用内小窗能力。

pipStyles.pipSize	object	否	无	应用内小窗尺寸配置。

pipStyles.pipSize.ratio	number	否	0.45	应用内小窗宽度与屏幕宽度的比例，取值范围为 (0, 1]。

pipStyles.allowedRoomStatuses	number[]	否	[1, 2, 3]	允许进入小窗或系统画中画的直播间状态列表。取值如下：

				* 1：直播中
				* 2：预告
				* 3：回放

enablePullRefresh	boolean	否	false	是否启用下拉刷新。仅在通过 `LivePlayerManager` 打开直播页面场景有效。

enableSwipeBack	boolean	否	true	是否启用侧滑返回手势。仅在通过 `LivePlayerManager` 打开直播页面场景有效。

uniStoragePrefetchKeys	\
	`string[]	boolean`	\
		否	无	控制是否同步 uni storage 到 H5 页面。传 `string[]` 时仅同步指定 key；传 `false` 时关闭同步。

步骤四：管理观播页面

您可通过以下方法管理观播页面：

| | | \

方法	说明

`LivePlayerManager.close({ mode: 'hide' })`	隐藏当前观播页面，后续可通过 `show()` 恢复。

`LivePlayerManager.close()`	关闭并销毁当前观播页面。

`LivePlayerManager.show()`	恢复大窗展示。

`LivePlayerManager.maximize()`	将观播页面从系统画中画恢复为大窗模式。

`LivePlayerManager.minimize()`	进入系统画中画。

`LivePlayerManager.enterInAppPiP()`	进入应用内小窗，返回是否成功发起。

`LivePlayerManager.exitMiniWindow()`	退出应用内小窗。

Native API 承接

uni-app 适配层会将 H5 发起的部分 Native API 请求代理到宿主 uni 能力，包括 navigateTo、redirectTo、switchTab、showToast、showModal、downloadFile、downloadFileAbort、saveImageToPhotosAlbum、requestPayment 和 share。本地存储 get / set / remove 请求通过 uni storage bridge 承接。宿主仍需要按业务场景确认权限、支付/分享 provider、相册权限和路由白名单等配置。

Android 接入

环境要求

Android 5.0（API Level 21）及以上；其中 Android 系统 PiP 依赖 Android 8.0（API Level 26）及以上，低版本仍可使用应用内小窗。
宿主工程建议使用 compileSdk / targetSdk 34 或以上；SDK 构建产物当前按 34 编译。
宿主工程需要配置 google() 与 mavenCentral()，用于解析 AndroidX 与 fastjson 依赖。
SDK 依赖 AndroidX core、appcompat、swiperefreshlayout、webkit 以及 fastjson。
如需使用系统 PiP，请按宿主 App 场景开启系统 Picture in Picture 能力；如需分享、支付、下载、相册等 Native API，由宿主自行声明权限并实现。

步骤一：引入 WebView SDK

点击下载 SDK 集成包。解压后，将 SDK 本地 Maven 仓库目录拷贝至您的 Android 工程中，例如放在 libs/bytelive-maven 下：
```
project
├── app
├── libs
│   └── bytelive-maven
└── settings.gradle
```

在工程中添加本地 Maven 仓库：

repositories {
    google()
    mavenCentral()
    maven {
        url uri("$rootDir/libs/bytelive-maven")
    }
}

添加 SDK 依赖：

dependencies {
    implementation "com.bytelive:byte-live-webview-sdk:0.1.0"
}

步骤二：创建 SDK 实例

通过 ByteLiveWebViewSdk.create() 创建 SDK 实例。

ByteLiveWebViewSdk sdk = ByteLiveWebViewSdk.create(
        activity,
        ByteLiveWebViewConfig.builder()
                .webViewDebugEnabled(true)
                .eventListener(event -> {
                    // 监听 SDK 事件
                })
                .bridgeHandler(new ByteLiveBridgeHandler() {
                    @Override
                    public void onInvokeNative(ByteLiveInvokeRequest request) {
                        // 处理 window.ByteLiveJsBridge.invokeNative(msg)
                    }

                    @Override
                    public void onNativeApiRequest(
                            ByteLiveNativeApiRequest request,
                            ByteLiveNativeApiResponder responder) {
                        // 处理 share / requestPayment / downloadFile / route / storage 等请求
                        responder.success(new JSONObject());
                    }
                })
                .build());

步骤三：配置观播页面

通过 attachContent() 配置观播页面信息。

sdk.attachContent(
        ByteLiveContentOptions.builder("live-content-xxx")
                .url("https://example.com/live")
                .top(0)
                .height(0)
                .autoplay(true)
                .navShellVisible(false)
                .miniWindowPosition(24, 120)
                .miniWindowSize(360, 202)
                .build());

参数说明如下所示：

| | | | | \

参数	是否必填	默认值	说明

`id`	是	无	观播页面内容的唯一标识，由业务自定义。该值与 `open()` 中的 `options.contentPlayerWebViewId` 对应，后续展示、隐藏、关闭和小窗控制会使用同一标识定位内容。

`url`	是	无	观播页面地址。

`top`	否	`0`	页面顶部偏移，单位为 px。

`height`	否	`0`	页面高度；为 `0` 或未传时，由 SDK 按宿主容器可用区域计算。

`autoplay`	否	`false`	是否自动播放。

`navShellVisible`	否	`false`	是否显示 SDK 内置导航容器。默认不显示，宿主可自行承接导航栏。

`miniWindowPosition`	否	SDK 默认位置	应用内小窗初始位置，例如 `miniWindowPosition(left, top)`。

`miniWindowSize`	否	SDK 默认尺寸	应用内小窗尺寸，例如 `miniWindowSize(width, height)`。

`navTitle`	否	无	SDK 内置导航容器标题。

`immersiveProgress`	否	`false`	是否使用沉浸式加载进度样式。

`keepSafeTop`	否	`false`	是否保留顶部安全区。

`miniWindowWidthRatio`	否	无	应用内小窗宽度占屏幕宽度的比例。

步骤四：展示观播页面

调用 showShell() 展示观播页面。

sdk.showShell("live-content-xxx");

iOS 接入

环境要求

iOS 12.0 及以上。
宿主工程使用 Xcode 14 或以上版本构建。
SDK 产物为 ByteLiveWebViewSdk.xcframework，同时包含 iPhoneOS 与 iPhone Simulator slice。
SDK 使用 Foundation、UIKit、WebKit、AVFoundation、AVKit、CoreMedia、QuartzCore、CFNetwork、CoreGraphics 等系统 Framework。
如需使用系统 PiP，请在宿主 App 开启 Picture in Picture 能力；分享、支付、相册、文件下载等业务能力由宿主自行声明权限并在 ByteLiveBridgeHandler 中处理。

步骤一：引入 WebView SDK

点击下载 SDK 集成包。解压后，把 ByteLiveWebViewSdk.xcframework 加入 Xcode 工程，并设置 Embed & Sign。
在代码中引入头文件：

#import <ByteLiveWebViewSdk/ByteLiveWebViewSdk.h>

步骤二：创建 SDK 实例

在 ViewController 中初始化 SDK，并实现协议：

@interface LiveHost () <ByteLiveEventListener, ByteLiveBridgeHandler>
@property (nonatomic, strong) ByteLiveWebViewSdk *sdk;
@end

初始化配置：

ByteLiveWebViewConfig *config = [ByteLiveWebViewConfig configWithEventListener:self
                                                                bridgeHandler:self];
config.webViewDebugEnabled = YES;

self.sdk = [ByteLiveWebViewSdk createWithViewController:self config:config];

步骤三：配置观播页面

通过 ByteLiveContentOptions 配置观播页面信息。

ByteLiveContentOptions *content = [[[[[[ByteLiveContentOptions optionsWithId:@"live-content-xxx"]
    url:@"https://example.com/live"]
    top:0]
    height:0]
    autoplay:YES]
    navShellVisible:NO];

| | | | | \

参数	是否必填	默认值	说明

`id`	是	无	观播页面内容的唯一标识，由业务自定义。该值与 `open()` 中的 `options.contentPlayerWebViewId` 对应，后续展示、隐藏、关闭和小窗控制会使用同一标识定位内容。

`url`	是	无	观播页面地址。

`top`	否	`0`	页面顶部偏移，单位为 px。

`height`	否	`0`	页面高度；为 `0` 或未传时，由 SDK 按宿主容器可用区域计算。

`autoplay`	否	`false`	是否自动播放。

`navShellVisible`	否	`false`	是否显示 SDK 内置导航容器。默认不显示，宿主可自行承接导航栏。

步骤四：展示观播页面

调用 showShell() 展示观播页面。

[self.sdk attachContent:content];
[self.sdk showShell:@"live-content-xxx"];

了解更多

WebView SDK API 参考

最近更新时间：2026.06.26 14:09:39

这个页面对您有帮助吗？

有用

无用

企业直播

适用场景

核心能力

最新版本

uni-app 接入

环境要求

步骤一：下载 SDK 集成包

步骤二：启用原生插件

步骤三：打开 WebView 页面

方式一：通过 LivePlayerManager 打开观播页面

方式二：通过 LivePlayer 组件集成直播能力

步骤四：管理观播页面

Native API 承接

Android 接入

环境要求

步骤一：引入 WebView SDK

步骤二：创建 SDK 实例

步骤三：配置观播页面

步骤四：展示观播页面

iOS 接入

环境要求

步骤一：引入 WebView SDK

步骤二：创建 SDK 实例

步骤三：配置观播页面

步骤四：展示观播页面

了解更多

方式一：通过 `LivePlayerManager` 打开观播页面

方式二：通过 `LivePlayer` 组件集成直播能力