本文介绍企业直播面向原生 App 内嵌场景的两个 WebView SDK：直播播放器 WebView SDK（byte-live-player） 与 uni web-view SDK（byte-live-webview）。两者定位与能力不同，请先选择适合的 SDK，再按对应章节接入。

前提条件 #

您已开通尊享版套餐。详见计费说明。

如何选择 WebView SDK #

• 若您需要支持应用内小窗（PiP），或需要提供宿主 App 提供分享、支付、下载、路由跳转等原生能力，请选择直播播放器 WebView SDK（byte-live-player）。
• 若您仅需要在 uni-app 中内嵌 H5 观看页，并解决 Android WebView 下连麦无法触发相机或麦克风系统权限弹窗的问题，希望轻量接入，请选择 uni web-view SDK（byte-live-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 接入 #

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）及以上版本；低版本设备仍可使用应用内小窗能力。
• Android 端如需在观播页面使用观众连麦功能，宿主 App 需具备摄像头和麦克风权限。WebView SDK 会承接 H5 与 uni-app 宿主之间的权限消息处理，您仍需在应用中声明相关 Android 权限，并确保应用具备对应运行时权限。
• iOS 端要求 iOS 12.0 及以上版本。iOS 插件会自动合并运行所需的系统 Framework、权限声明及相关配置，开发者无需手动添加。
• 如需在 iOS 模拟器中进行调试，请使用包含 Simulator Slice 的自定义基座或 .xcframework 产物。真机基座与模拟器基座不兼容，不能混用。

步骤一：下载 SDK 集成包

1. 点击下载 SDK 集成包：
   
   

   byte-live-player-delivery-0.0.16.zip

   未知大小

   
   
   集成包目录如下所示：

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

2. 解压 SDK 包，将 nativeplugins/byteLivePlayer 和 uni_modules/byte-live-player 分别拷贝到 uni-app 工程的同名目录下。
3. （可选）如果您的 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，否则运行时将无法调用相关能力。

1. 您可通过以下两种方式启用：
   • 方式一：通过 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
                     }
                 }
             }
         }
     }
     

2. 修改原生插件配置后，需要重新制作并安装包含该插件的自定义调试基座，或重新执行云打包或离线打包应用，否则插件不会生效。在代码中，可通过以下代码验证插件是否已生效：

   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 参考。

步骤四：管理观播页面

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

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

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

   byte-live-webview-sdk-local-maven-0.1.0.zip

   未知大小

   

   project
   ├── app
   ├── libs
   │   └── bytelive-maven
   └── settings.gradle
   

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

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

3. 添加 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());

参数说明如下所示：

步骤四：展示观播页面

调用 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

1. 点击下载 SDK 集成包。解压后，把 ByteLiveWebViewSdk.xcframework 加入 Xcode 工程，并设置 Embed & Sign。
   
   

   ByteLiveWebViewSdk.xcframework-0.1.0.zip

   未知大小

   
2. 在代码中引入头文件：

#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];

步骤四：展示观播页面

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

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

uni web-view SDK #

如果您的项目仅需在 uni-app 中加载企业直播 H5 页面，并承接 H5 与宿主之间的消息通信、Android 运行时权限申请等能力，可以接入 uni web-view SDK。该 SDK 是面向 Uni 环境的专用 SDK 包，以纯 JavaScript 的 uni_modules 组件形式交付。

• 当前版本：0.3.0
• 支持范围：uni-app Vue 2 / Vue 3，App Android、App iOS 和 H5
• 交付形式：uni_modules，不包含原生插件、AAR 或 Framework

步骤一：安装 SDK #

安装 SDK：获取 SDK 压缩包并解压，将 uni_modules/byte-live-webview 目录复制到 uni-app 项目根目录下。

byte-live-webview-delivery-0.3.0.zip

未知大小

你的 uni-app 项目/
└── uni_modules/
    └── byte-live-webview/
        ├── components/
        ├── js/
        ├── static/
        ├── web/
        ├── index.js
        └── package.json

步骤二：注册组件 #

在项目的 pages.json 中增加 easycom 配置。如果项目已有 easycom，只需合并 custom 中的组件规则：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^ByteLiveWebView$": "@/uni_modules/byte-live-webview/components/ByteLiveWebView.vue"
    }
  }
}

步骤三：在页面中使用 #

在需要加载观播页面的位置使用 ByteLiveWebView 组件。

<template>
  <view class="page">
    <ByteLiveWebView
      :src="liveUrl"
      :webview-styles="webviewStyles"
      @message="onMessage"
      @load="onLoad"
      @error="onError"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      liveUrl: 'https://example.com/live/index.html',
      webviewStyles: {
        top: '0px',
        bottom: '0px'
      }
    };
  },
  methods: {
    onMessage(event) {
      // 透传 H5 的原始消息，数据位于 event.detail.data。与 uni-app 原生 <web-view @message> 的数据结构一致。
      console.log('收到 H5 消息：', event.detail.data);
    },
    onLoad(event) {
    // WebView 页面加载完成。
      console.log('页面加载完成：', event);
    },
    onError(event) {
    // WebView 页面加载失败，或 Android WebView 初始化失败。
      console.error('页面加载失败：', event);
    }
  }
};
</script>

常用配置说明如下所示：

<ByteLiveWebView
  :src="liveUrl"
  :override-resource-request="[
    {
      match: '^https://example\\.com/live/assets/app\\.js(?:\\?.*)?$',
      redirect: '_www/static/offline/app.js',
      mime: 'application/javascript',
      encoding: 'UTF-8'
    }
  ]"
/>

常用事件说明如下所示：

步骤四：配置 Android 运行时权限 #

如果 H5 需要申请相机、麦克风等权限，例如用于观众连麦，需要在宿主项目的 manifest.json 中声明对应权限，您也可以在组件中设置 allowedPermissions 权限白名单。

1. （可选）在组件中设置权限白名单：

   <ByteLiveWebView
     :src="liveUrl"
     :allowed-permissions="[
       'android.permission.CAMERA',
       'android.permission.RECORD_AUDIO'
     ]"
   />
   

2. 在宿主项目的 manifest.json 中声明对应权限。运行时申请不能代替 manifest.json 声明，两者必须同时配置。

   {
     "app-plus": {
       "distribute": {
         "android": {
           "permissions": [
             "<uses-permission android:name=\"android.permission.CAMERA\"/>",
             "<uses-permission android:name=\"android.permission.RECORD_AUDIO\"/>"
             "<uses-permission android:name=\"android.permission.MODIFY_AUDIO_SETTINGS\"/>"
           ]
         }
       }
     }
   }
   

   上述权限说明如下所示：
   • CAMERA：视频连麦所需的摄像头权限。
   • RECORD_AUDIO：音频、视频连麦所需的麦克风权限。
   • MODIFY_AUDIO_SETTINGS：连麦音频链路所需的音频设置权限。

   说明

   App iOS 不提供同类批量权限接口，具体权限仍由相机、定位等业务 API 在实际调用时触发。

了解更多 #

WebView SDK API 参考