Flutter视频质量监控插件conviva_tracker的使用

conviva_tracker 是一个用于在 Flutter 应用中集成 Conviva 视频质量监控的插件。Conviva 是一个强大的视频分析平台，能够帮助开发者监控视频播放的性能和质量，包括缓冲时间、播放错误、视频启动时间等关键指标。

以下是如何在 Flutter 项目中使用 conviva_tracker 插件的基本步骤：

1. 添加依赖

首先，在 pubspec.yaml 文件中添加 conviva_tracker 插件的依赖：

dependencies:
  flutter:
    sdk: flutter
  conviva_tracker: ^1.0.0  # 请使用最新版本

然后运行 flutter pub get 来安装依赖。

2. 初始化 Conviva

在你的 Flutter 应用中，首先需要初始化 Conviva。通常在 main.dart 文件中进行初始化：

import 'package:conviva_tracker/conviva_tracker.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 初始化 Conviva
  ConvivaTracker.initialize(
    customerKey: 'YOUR_CUSTOMER_KEY',  // 替换为你的 Conviva 客户密钥
    gatewayUrl: 'https://YOUR_GATEWAY_URL',  // 替换为你的 Conviva Gateway URL
    logLevel: ConvivaLogLevel.debug,  // 设置日志级别
  );

  runApp(MyApp());
}

3. 创建 Conviva 会话

在开始播放视频时，创建一个 Conviva 会话。会话用于跟踪视频播放的各个阶段。

import 'package:conviva_tracker/conviva_tracker.dart';

class VideoPlayerScreen extends StatefulWidget {
  [@override](/user/override)
  _VideoPlayerScreenState createState() => _VideoPlayerScreenState();
}

class _VideoPlayerScreenState extends State<VideoPlayerScreen> {
  ConvivaSession? convivaSession;

  [@override](/user/override)
  void initState() {
    super.initState();

    // 创建 Conviva 会话
    convivaSession = ConvivaSession.createSession(
      assetName: 'My Video',  // 视频名称
      viewerId: 'user123',  // 用户 ID
      streamType: StreamType.live,  // 视频类型：直播或点播
    );
  }

  @Override
  void dispose() {
    // 结束 Conviva 会话
    convivaSession?.endSession();
    super.dispose();
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Video Player'),
      ),
      body: Center(
        child: VideoPlayerWidget(),  // 你的视频播放器组件
      ),
    );
  }
}

4. 发送事件

在视频播放的不同阶段，发送事件以监控视频播放的质量。例如，在视频开始播放时发送 play 事件，在视频暂停时发送 pause 事件。

void onVideoPlay() {
  convivaSession?.sendEvent(ConvivaEventType.play);
}

void onVideoPause() {
  convivaSession?.sendEvent(ConvivaEventType.pause);
}

void onVideoError(String errorMessage) {
  convivaSession?.sendEvent(ConvivaEventType.error, errorMessage: errorMessage);
}

5. 监控视频质量

Conviva 会自动收集视频播放的质量数据，并将其发送到 Conviva 平台。你可以在 Conviva 仪表板中查看这些数据，分析视频播放的性能和质量。

6. 结束会话

在视频播放结束时，记得结束 Conviva 会话：

void onVideoEnd() {
  convivaSession?.endSession();
}

7. 处理错误

如果视频播放过程中出现错误，可以通过 Conviva 会话发送错误事件：

void onVideoError(String errorMessage) {
  convivaSession?.sendEvent(ConvivaEventType.error, errorMessage: errorMessage);
}

8. 高级配置

conviva_tracker 还支持更多高级配置，如自定义元数据、设置用户 ID、调整日志级别等。你可以根据需要进行配置。

ConvivaTracker.setMetadata({
  'custom_key': 'custom_value',
});

ConvivaTracker.setUserId('user123');

9. 调试与日志

在开发过程中，你可以通过设置日志级别来查看详细的日志信息，以便调试和排查问题。

ConvivaTracker.setLogLevel(ConvivaLogLevel.debug);

10. 集成视频播放器

conviva_tracker 可以与任何视频播放器集成，如 video_player、chewie 等。你只需要在视频播放器的回调中发送相应的事件即可。

VideoPlayerController _controller;

[@override](/user/override)
void initState() {
  super.initState();
  _controller = VideoPlayerController.network('https://www.example.com/video.mp4')
    ..initialize().then((_) {
      setState(() {});
    });

  _controller.addListener(() {
    if (_controller.value.isPlaying) {
      convivaSession?.sendEvent(ConvivaEventType.play);
    } else {
      convivaSession?.sendEvent(ConvivaEventType.pause);
    }
  });
}