本文介绍如何使用 Flutter 直播间观播 SDK 进入直播间、离开直播间、设置直播间状态回调等。

前提条件

您已完成 Flutter 直播间观播 SDK 的集成。详见集成 Flutter 直播间观播 SDK。

示例 Demo

点击此处，下载查看示例代码。

使用 SDK

引入头文件

import 'package:bdlive_flutter_viewer/bdlive_flutter_viewer.dart';

初始化 SDK

建议在项目的 main.dart 文件中，通过 runApp 方法初始化 SDK，以确保 SDK 正确的初始化顺序。

TTSDKConfiguration config = TTSDKConfiguration(
  appID: 'APP_ID',// 将 APP_ID 替换为在 SDK 应用创建后生成的 App ID。
  bundleID: 'BUNDLE_ID', // 将 BUNDLE_ID 替换为 iOS App 的唯一标识（Bundle Identifier）。
  appName: 'APP_NAME', // 将 APP_NAME 替换为创建 SDK 应用时填写的 App 英文名称。
  channel: 'CHANNEL_NAME', // 将 CHANNEL_NAME 替换为 App 的渠道名称，例如 App Store。
  vodLicenseFilePath: 'VOD_LICENSE_PATH', // 将 VOD_LICENSE_PATH 替换为点播 License 文件的路径，例如 assets/vod.lic。
  liveLicenseFilePath: 'LIVE_LICENSE_PATH', // 将 LIVE_LICENSE_PATH 替换为直播 License 文件的路径，例如 assets/live.lic。
  appVersion: 'APP_VERSION',  // 将 APP_VERSION 替换为 App 的版本号。合法版本号应包含 2 个或以上的分隔符，例如 1.3.2。
);
BdliveViewerApi.startWithConfiguration(config);

完整直播间

进入直播间

您可以通过以下示例代码，让观众进入完整直播间并在 App 内显示完整直播间页面。

/**
 * @param activity：进入直播间所需的信息。
 */
Future<bool> enterLiveRoom(BdlActivityConfig activity);

相关类型详情，详见 BdlActivityConfig。

离开直播间

在观众退出您的观看页面时，您可以通过以下示例代码，离开完整直播间。如果正在显示浮窗播放器，则同时销毁浮窗播放器。

Future<void> leaveLiveRoom();

在观众退出您的观看页面时，您可以通过以下示例代码，离开完整直播间。如果观众正在观看视频，则同时显示浮窗播放器。

Future<void> manualClickLiveRoomExitBtn();

设置直播间状态回调

设置直播间状态回调，监听完整直播间页面的事件。

Future<void> setLiveRoomStatusListener(BdlLiveRoomStatusListener listener);

直播间状态回调

class BdlLiveRoomStatusListener {
  /**
   * 直播间切换到前台回调。
   * @param activity：进入直播间所需的信息。
   */
  void Function(BdlActivityConfig activity)? onLiveRoomActivityResume;

  /**
   * 直播间切换到后台回调。
   * @param activity：进入直播间所需的信息。
   */
  void Function(BdlActivityConfig activity)? onLiveRoomActivityPause;

  /**
   * 浮窗播放器即将显示回调。
   * @param activity：进入直播间所需的信息。
   */
  void Function(BdlActivityConfig activity)? onFloatViewWillAppear;

  /**
   * 浮窗播放器即将消失回调。
   * @param activity：进入直播间所需的信息。
   */
  void Function(BdlActivityConfig activity)? onFloatViewWillClose;

  /**
   * 配置了跳转链接的商品卡片（菜单内商品卡片、浮窗商品卡片）和广告（页头广告、页中广告、浮标广告）点击回调。
   * @param url：商品卡片或广告配置的跳转链接。
   * @param type：跳转链接所属的内容类型。
   * @param enableFloating：企业直播服务端返回的是否在观看页浮层展示内容的设置。
      true：在观看页浮层展示内容。
      false：在新页面展示内容。
   */
  void Function(String url, BdlViewerOpenUrlType type, bool enableFloating)? onOpenUrlCallback;
}

相关类型详情，详见 BdlActivityConfig 和 BdlViewerOpenUrlType。

纯净播放器

创建并启动播放器

启动播放器后，会触发资源可播放状态变化回调。仅在 BdlivePlayableStatus 的值不为 unknown 时，可以调用纯净播放器的其他方法。

// 创建播放器。
// @param activity 播放器配置信息。
static Future<BdliveViewerPlayer> createPlayer(BdlViewerPlayerConfig activity);
// 启动播放器，并根据播放器配置信息（BdlViewerPlayerConfig）进入直播间。
Future<void> start();

相关类型详情，详见 BdlViewerPlayerConfig。

播放控制

// 播放。
Future<void> play();
// 暂停播放。
Future<void> pause();

获取播放信息

// 获取是否正在播放视频。
Future<bool?> isPlaying();
// 获取当前视频是否卡顿。
Future<bool?> isStalling();
// 获取当前资源的可播放状态。
Future<BdlivePlayableStatus> getPlayableStatus();
// 获取当前点播视频的播放进度，单位为毫秒。在 BdlivePlayableStatus 的值为 vodCanPlay 时，可调用此方法。
Future<int?> getCurVodPlayTime();
// 获取当前点播视频的时长，单位为毫秒。在 BdlivePlayableStatus 的值为 vodCanPlay 时，可调用此方法。
Future<int?> getCurVodDuration();

相关类型详情，详见 BdlivePlayableStatus。

视频画面填充模式

设置视频画面填充模式

// 设置视频画面填充模式。
// @param playerLayoutMode 视频画面填充模式。
Future<void> setPlayerLayoutMode(BdlivePlayerLayoutMode playerLayoutMode);

相关类型详情，详见 BdlivePlayerLayoutMode。

获取视频画面填充模式

Future<BdlivePlayerLayoutMode?> getPlayerLayoutMode();

相关类型详情，详见 BdlivePlayerLayoutMode。

清晰度

获取支持的清晰度列表

// 获取支持的清晰度列表。
Future<List<BdliveVideoResolution>?> getResolutions();

相关类型详情，详见 BdliveVideoResolution。

获取当前清晰度

// 获取当前清晰度。
Future<BdliveVideoResolution> getCurResolution();

相关类型详情，详见 BdliveVideoResolution。

切换当前清晰度

// 切换当前清晰度。
// @param resolution 切换后的清晰度。
Future<void> setCurResolution(BdliveVideoResolution resolution);

相关类型详情，详见 BdliveVideoResolution。

跳转至点播视频的指定时间点

// 跳转至点播视频的指定时间点。在 BdlivePlayableStatus 的值为 vodCanPlay 时，可调用此方法。
// @param timeInMills 跳转到的指定时间点。单位为毫秒。
Future<bool?> seekVodTime(int timeInMills);

相关类型详情，详见 BdlivePlayableStatus。

设置静音

// 设置静音，默认不静音。
// @param isMute 是否静音。
Future<void> setMute(bool isMute);

设置循环播放点播视频

// 设置循环播放点播视频，默认不循环播放。在 BdlivePlayableStatus 的值为 vodCanPlay 时，可调用此方法。
// @param isLoop 是否循环播放。 
Future<void> setVodLoop(bool isLoop);

相关类型详情，详见 BdlivePlayableStatus。

倍速播放

获取点播视频播放速度

// 获取点播视频播放速度。在 BdlivePlayableStatus 的值为 vodCanPlay 时，可调用此方法。返回值取值范围为 (0,2]。如果当前未播放点播视频，则返回值为 -1。
Future<double?> getCurVodPlaySpeed();

相关类型详情，详见 BdlivePlayableStatus。

设置倍速播放点播视频

// 设置倍速播放点播视频。在 BdlivePlayableStatus 的值为 vodCanPlay 时，可调用此方法。
// @param playSpeed 播放倍速。默认值为 1。取值范围为 (0,2]
Future<void> setVodPlaySpeed(double playSpeed);

相关类型详情，详见 BdlivePlayableStatus。

获取直播间状态

Future<BdLiveRoomStatus> getLiveRoomStatus();

相关类型详情，详见 BdLiveRoomStatus。

设置封面图显示状态

// 设置封面图显示状态。
// @param visible 封面图显示状态。默认值为 true，即显示封面图。取值为 false 时，表示强制隐藏封面图。
Future<void> setCoverImageContainerVisibility(bool visible);

通知 SDK 播放器的后台运行状态

// 通知 SDK 播放器的后台运行状态。当播放器在后台运行时，即播放器不可见时，您可将参数值设置为 true，调用该方法。
// @param inBackground 播放器是否在后台运行。true 表示播放器在后台运行，即播放器不可见，false 表示播放器在前台运行，即播放器可见。默认值为 false。
Future<void> setInBackground(bool inBackground);

设置播放状态回调

Future<void> setDelegate(BdliveViewerPlayerDelegate delegate);

播放状态回调

class BdliveViewerPlayerDelegate {
  /// 直播间状态变化回调。
  /// @param status 当前直播间状态。
  void Function(BdLiveRoomStatus status)? liveRoomStatusChanged;
  /// 资源可播放状态变化回调。
  /// @param playableStatus 当前资源的可播放状态。
  void Function(BdlivePlayableStatus playableStatus)? playableStatusChanged;
  /// 播放状态变化回调。
  /// @param isPlaying 当前是否正在播放。 
  void Function(bool isPlaying)? isPlayingChanged;
  /// 视频画面尺寸变化回调。
  /// @param width 视频宽度。
  /// @param height 视频高度。 
  void Function(int width, int height)? videoSizeChanged;
  /// 视频卡顿状态变化回调。您可以自行配置是否显示自定义加载动画。
  /// @param isStalling 当前视频是否卡顿。
  void Function(bool isStalling)? isStallingChanged;
  /// 点播发生错误回调。
  /// @param error 错误详情。  
  void Function(BdliveError error)? vodErrorOccurred;
  /// 直播发生错误回调。
  /// @param error 错误详情。
  void Function(BdliveError error)? liveErrorOccurred;
  /// 视频播放发生错误回调，包括点播发生错误和直播发生错误。此时播放处于暂停状态，您可以自行配置重试画面，引导观众点击重试播放。
  /// @param isPlayError 当前是否发生播放错误。
  void Function(bool isPlayError)? playErrorStatusChanged;
  /// 点播视频已准备完毕回调。
  void Function()? vodPrepared;
  /// 点播视频画面渲染开始回调。
  void Function()? vodRenderStarted;
  /// 点播视频自动断点续播回调。
  /// @param seekTimeInMills 自动断点续播后跳转到的视频播放位置。单位为毫秒。
  void Function(int seekTimeInMills)? vodAutoSeekPreviousTime;
  /// 点播视频当前播放进度变化回调。每秒更新一次。
  /// @param curTimeInMills 当前播放进度。单位为毫秒。
  void Function(int curTimeInMills)? vodCurPlayTimeChanged;
  /// 点播视频总时长变化回调。此回调通常在视频切换时触发。
  /// @param durationInMills 当前视频的总时长。单位为毫秒。
  void Function(int durationInMills)? vodDurationChanged;
  /// 直播已准备完毕回调。
  void Function()? livePrepared;
  /// 直播渲染开始回调。直播过程中可能会发生重试导致多次触发此回调。
  /// @param isFirstFrame 是否为真正渲染的第一帧，即是否是调用 play 方法后的第一帧。
  void Function(bool isFirstFrame)? liveFirstFrameRendered;
  /// 封面可见状态变化回调。视频播放时封面不可见，无视频播放时封面可见。
  /// @param isVisible 封面是否可见。  
  void Function(bool isVisible)? coverImageVisibleChanged;
  /// 视频清晰度信息变化回调。此回调通常在视频切换时触发。
  /// @param resolutions 当前支持的清晰度列表。
  /// @param defaultResolution 当前默认选中的清晰度。 
  void Function(List<BdliveVideoResolution> resolutions, BdliveVideoResolution defaultResolution)? resolutionInfoChanged;
  /// 封面图尺寸变化回调。
  /// @param width 封面图宽度。
  /// @param height 封面图高度。  
  void Function(int width, int height)? coverImageSizeChanged;
  /// 在观众被强制退出直播间时，SDK 触发该回调。
  /// @param  reason 观众被强制退出直播间的原因。
  void Function(BdliveForceOfflineReason reason)? onUserForceOffline;
  /// 播放器释放回调。SDK 触发该回调后，不可再调用任何播放器的方法。
  void Function()? onRelease;
  }

相关类型详情，详见 BdLiveRoomStatus、BdlivePlayableStatus、BdliveError、BdliveVideoResolution、BdliveForceOfflineReason。

销毁播放器

Future<void> destroy();

自定义配置

加载商品卡片和广告的跳转链接

观众点击配置了跳转链接的菜单内商品卡片、浮窗商品卡片、页头广告、页中广告或浮标广告后，默认不会加载跳转链接。如需加载跳转链接，您可以通过 onOpenUrlCallback 回调监听观众的点击行为，并调用以下方法，执行后续 SDK 默认的跳转行为。

/**
 * @param url：商品卡片或广告配置的跳转链接。
 * @param type：跳转链接所属的内容类型。
 * @param enableFloating：是否在观看页浮层展示内容。
    true：在观看页浮层展示内容，即在完整直播间的页面中弹出 WebView 弹窗展示跳转链接的内容。
    false：在新页面展示内容，即通过 App 的 DeepLink 机制寻找符合条件的页面展示跳转链接的内容。
 */
Future<void> openUrl(String url, BdlViewerOpenUrlType type, bool enableFloating);

相关类型详情，详见 BdlViewerOpenUrlType。