# @bitmovin/player-integration-conviva 中文文档

规范地址：https://npmcn.com/package/%40bitmovin/player-integration-conviva/

版本：6\.3\.0
npm 元数据更新时间：2026-11-05T09:04:41.494Z
中文译文更新时间：2026-11-08T04:36:22.453Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bitmovin/player-integration-conviva
原文对照：https://npmcn.com/package/%40bitmovin/player-integration-conviva/?lang=original
项目主页：https://github.com/bitmovin/bitmovin-player-analytics-conviva#readme
源码仓库：https://github.com/bitmovin/bitmovin-player-analytics-conviva

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：510 kB，92 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：bitmovin-player ^8\.193\.0，@convivainc/conviva-js-coresdk ^4\.7\.6
- 首次发布：2019-03-08T12:30:02.735Z
- 最新版本发布：2026-06-18T11:40:03.624Z
- 近 30 天下载量：20386（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 3 个）

## 中文简介

Bitmovin 玩家的 Conviva 分析集成

## 安装

```sh
npm install @bitmovin/player-integration-conviva
```

也可以使用：`pnpm add @bitmovin/player-integration-conviva`、`yarn add @bitmovin/player-integration-conviva`、`bun add @bitmovin/player-integration-conviva`

## README

# Bitmovin 玩家 Conviva 分析集成

这是一个开源项目,可以使用与Bitmovin Player Web SDK的第三方组件(Conviva).

## 维护和更新

该项目不是定期维护或更新时间表的一部分,每年更新一次,以符合最新产品版本。 关于其他更新请求,请进一步参考下文的指导意见.

## 对该项目的捐款

作为一个开源项目,我们高兴地接受希望使用该项目的社区的任何和所有改变、更新和修正。 请看 [捐款额](https://npmcn.com/package/%40bitmovin/player-integration-conviva/CONTRIBUTING.md) 详细了解如何捐款.

## 报告玩家错误

如果您遇到与玩家相关的错误,请通过支持出票系统提高这个.

## 需要更多帮助吗?

如果您需要帮助更新此项目( 更新、 修改、 修补等) , 且无法因任何原因做出贡献, 请向您的比特movin 帐号团队提出您的请求, 该团队可以讨论您的请求 .

## 支助和苏丹解放军免责声明

作为一项开源项目,而不是核心产品提供,与该项目有关的任何请求、问题或查询都被排除在客户可能与Bitmovin或其他第三方服务提供者或公司共同参与该项目的任何SLA和支持条款之外。 任何更新都完全由贡献者自行决定.

谢谢你的贡献!

## 兼容性

**这个版本的Conviva分析集成只与玩家版本QQ8.31.x.** Conviva SDK的推荐和测试版本为4.5.7. 见 [变动情况](https://npmcn.com/package/%40bitmovin/player-integration-conviva/CHANGELOG.md) 详细情况.

## 开始

### 安装

#### 利用国家预防机制

安装 npm 包 :

```
npm i @bitmovin/player-integration-conviva --save-dev
```

#### 使用自定义构建

通过运行构建 JS 文件 `npm run build`

### 发展中国家

1.  克隆 Git 仓库
2.  安装节点.js
3.  安装所需的 npm 包 : [`npm install`](https://www.npmjs.com/)
4.  运行任务 :

-   `npm run lint` 输入类型脚本文件以及 ChangeGELOG.md
-   `npm run build` 将项目建入 `dist` 目录
-   `npm run start` 在浏览器中打开测试页面,自动构建并重新加载已修改的文件
-   `npm run format` 来运行更漂亮和自动格式化的所有代码文件
-   `npm run test` 运行测试

## 使用量

1.  包含 `conviva-core-sdk.min.js` 作为 **第一个** hTML 文档中的所有脚本
    
2.  创建实例 `ConvivaAnalytics` **在此之前** 电话 `player.load(...)` 并传入你的Conviva `CUSTOMER_KEY` 和可选配置属性 :
    
    1.  使用国家防范机制导入:
        
        1.  导入 Conviva 分析 :
            
            ```typescript
            import { ConvivaAnalytics } from '@bitmovin/player-integration-conviva';
            ```
            
        2.  使用量
            
            ```typescript
            const playerConfig = {
              key: 'YOUR-PLAYER-KEY',
              // ...
            };
            
            const player = new Player(document.getElementById('player'), playerConfig);
            const conviva = new ConvivaAnalytics(player, 'CUSTOMER_KEY', {
              debugLoggingEnabled: true, // optional
              gatewayUrl: 'https://youraccount-test.testonly.conviva.com', // optional, TOUCHSTONE_SERVICE_URL for testing
              deviceCategory: Conviva.Client.DeviceCategory.WEB, // optional, deprecated (Use deviceMetadata.category) (default: WEB)
              deviceMetadata: {
                // optional (default: let Conviva backend infer these fields from User Agent string)
                category: Conviva.Client.DeviceCategory.WEB, // optional (default: WEB)
                brand: 'Device brand', // optional
                manufacturer: 'Device Manufacturer', // optional
                model: 'Device Model', // optional
                type: Conviva.Client.DeviceType.DESKTOP, // optional
                version: 'Device version', // optional
                osName: 'Operating system name', // optional
                osVersion: 'Operating system version', // optional
              },
            });
            
            var sourceConfig = {
              // ...
            };
            
            player.load(sourceConfig).then(
              function () {
                console.log('player loaded');
              },
              function (reason) {
                console.error('player setup failed', reason);
              },
            );
            ```
            
    2.  使用自定义构建 :
        
        1.  包含 `bitmovinplayer-analytics-conviva.js` **之后** `conviva-core-sdk.min.js` 在您的 HTML 文档中
            
        2.  使用量
            
            ```js
            var playerConfig = {
              key: 'YOUR-PLAYER-KEY',
              // ...
            };
            
            var container = document.getElementById('player');
            var player = new bitmovin.player.Player(container, playerConfig);
            
            // A ConvivaAnalytics instance is always tied to one player instance
            var conviva = new bitmovin.player.analytics.ConvivaAnalytics(player, 'CUSTOMER_KEY', {
              debugLoggingEnabled: true, // optional
              gatewayUrl: 'https://youraccount-test.testonly.conviva.com', // optional, TOUCHSTONE_SERVICE_URL for testing
              deviceCategory: Conviva.Client.DeviceCategory.WEB, // optional, (default: WEB)
            });
            
            var sourceConfig = {
              // ...
            };
            
            player.load(sourceConfig).then(
              function () {
                console.log('player loaded');
              },
              function (reason) {
                console.error('player setup failed', reason);
              },
            );
            ```
            
3.  通过调用释放实例 `conviva.release()` 在通过调用来毁灭玩家之前 `player.destroy()`
    

### 高级使用

#### 虚拟平台追踪

如果您想在未发生实际玩家出错(如:. 服务器关闭连接并返回 `net::ERR_EMPTY_RESPONSE` 或经过一段时间的拖延) 您可以使用跟踪API来跟踪这些缺陷.

```js
conviva.reportPlaybackDeficiency('Some Error Message', Conviva.Client.ErrorSeverity.FATAL);
```

_见 [ConvivaAnalytics.ts 数据分析](https://npmcn.com/package/%40bitmovin/player-integration-conviva/src/ts/ConvivaAnalytics.ts) 参数细节._

Conviva建议在报告一个错误集合和提供用户反馈之前,暂停时间为~10秒左右.

#### 内容元数据处理

如果您想要覆盖一些内容元数据属性,您可以添加以下内容:

```js
let metadataOverrides = {
  applicationName: 'App Name',
  viewerId: 'uniqueViewerId',
  custom: {
    customTag: 'customValue',
  },
  // Find the list here https://pulse.conviva.com/learning-center/content/sensor_developer_center/sensor_integration/javascript/js_quick_integration.htm
  // under "Constants for Pre-defined Video and Content Metadata"
  additionalStandardTags: {
    'c3.cm.channel': 'Test Channel',
    'c3.cm.brand': 'Test Brand',
  },
  encodedFrameRate: 24,
  // …
};

// …
// Initialize ConvivaAnalytics
// …

conviva.updateContentMetadata(metadataOverrides);
```

这些值将在会议结束后清理.

_见 [ConvivaAnalytics.ts 数据分析](https://npmcn.com/package/%40bitmovin/player-integration-conviva/src/ts/ConvivaAnalytics.ts) 关于更多属性的细节._

如果您需要将 Conviva 管理的元数据与自定义元数据分开配置, 请使用专门的 API :

```js
conviva.updateRequiredContentMetadata({
  assetName: 'My Asset',
  viewerId: 'uniqueViewerId',
  streamType: Conviva.ContentMetadata.StreamType.UNKNOWN,
});

conviva.updateCustomContentMetadata({
  custom: {
    streamType: 'dash_vod',
    customTag: 'customValue',
  },
  additionalStandardTags: {
    'c3.cm.channel': 'Test Channel',
  },
});
```

当您想要发送 Conviva 需要时, 这会有所帮助 `streamType` 数值(`UNKNOWN`, (中文(简体) ), `VOD`, (中文(简体) ), `LIVE`)并发送任意的习惯 `streamType` 标记为平行.

#### 连续播放

如果您想要使用同一玩家实例进行多次回放, 请只需加载新源 `player.load(…)`。 。 。 . 合并将结束活动会议.

```js
player.load({…});
```

#### 外部 VST 跟踪

如果您的应用程序需要额外的设置步骤, 应当在 VST 跟踪中包含这些步骤, 如 DRM 令牌生成 `Player` 实例可以初始化, 页:1 `ConvivaAnalytics` 可以在不附带条件的情况下初始化 `Player` 举个例子 一旦 `Player` 实例可以附加.

1.  创建 `ConvivaAnalytics` 与您的实例 `customerKey` 和配置.

```typescript
const convivaAnalytics = new ConvivaAnalytics(undefined, customerKey);
```

2.  Conviva要求: `assetName` 设置在会话初始化时。 因此确保您使用元数据覆盖提供 **在此之前** 启动跟踪会话.

```typescript
convivaAnalytics.updateRequiredContentMetadata({
  assetName: 'Your Asset Name',
});

// Initialize tracking session
convivaAnalytics.initializeSession();
```

3.  曾经 `Player` 实例已准备好附在 `ConvivaAnalytics` 举个例子.

```typescript
// ... Additional setup steps

const player = new bitmovin.player.Player(document.getElementById('player'), getPlayerConfig());
convivaAnalytics.attachPlayer(player);
```

## 常见问题

### @bitmovin/player-integration-conviva 是什么？

Bitmovin 玩家的 Conviva 分析集成

### 如何安装 @bitmovin/player-integration-conviva？

在项目目录运行 npm install @bitmovin/player-integration-conviva，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：bitmovin-player（^8\.193\.0）、@convivainc/conviva-js-coresdk（^4\.7\.6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bitmovin/player-integration-conviva 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bitmovin/player-integration-conviva 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bitmovin/player-integration-conviva 可以商用吗？

@bitmovin/player-integration-conviva 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bitmovin/player-integration-conviva 的下载量有多少？

根据 npm 官方下载统计，@bitmovin/player-integration-conviva 在 2026/10/08 – 2026/11/06 这 30 天内被下载 20,386 次，日均约 680 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bitmovin/player-integration-conviva 还在维护吗？

最新版本 6\.3\.0 发布于 2026/06/18（4 个月前）；至今共发布 29 个版本，其中过去 12 个月发布了 3 个；首次发布于 2019/03/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。