Close Menu

theoplayer-connector-conviva

Welcome to the documentation for THEOplayer Connector for Conviva! This documentation will guide you through the integration steps and provide you with all necessary information to successfully use the THEOplayer Connector for Conviva.

Table of Contents

Introduction

The THEOPlayer Connector for Conviva is a powerful integration that enables you to monitor your THEOPlayer-powered video player using Conviva’s real-time analytics and video intelligence. It allows for measuring viewer experience metrics, quality of service, and engagement data, helping you optimize your video delivery and improve overall user experience.

Installation

To install the THEOPlayer Connector for Conviva, follow the steps below:

Step 1: Include Conviva JavaScript Library

First, you need to include the Conviva JavaScript library in your web page. This library provides the necessary functionality for integrating with Conviva’s services. You can include it by adding the following script tag to the head section of your HTML:

// Replace "YOUR_CONVIVA_JS_SDK_URL" with the actual URL to Conviva JavaScript SDK
<script src="YOUR_CONVIVA_JS_SDK_URL"></script>

Step 2: Include THEOplayer Script

Next, make sure you have included the THEOplayer script in your web page. This is necessary to use the THEOplayer player instance with the Conviva integration. You can include it by adding the following script tag to the head section of your HTML:

// Replace "YOUR_THEOPLAYER_SCRIPT_URL" with the actual URL to THEOPlayer script
<script src="YOUR_THEOPLAYER_SCRIPT_URL"></script>

Step 3: Install THEOplayer Connector for Conviva

Finally, you need to install the THEOplayer Connector for Conviva library. This library provides the integration between THEOplayer and Conviva’s analytics platform. You can install it via NPM or by including a script tag pointing to the library file:

// Install via NPM
npm install theoplayer-connector-conviva

// OR include via script tag
<script src="YOUR_THEOPLAYER_CONNECTOR_CONVIVA_SCRIPT_URL"></script>

Usage

Using the THEOPlayer Connector for Conviva is straightforward. Follow the steps below to integrate Conviva analytics with your THEOPlayer-powered video player.

Step 1: Initialize Conviva Client

Before you can start monitoring your THEOPlayer player, you need to initialize the Conviva client. You can do this by creating an instance of the ConvivaClient class and calling the initialize method. Pass your Conviva customer key and the Conviva JavaScript library instance as arguments. For example:

// Replace "YOUR_CONVIVA_CUSTOMER_KEY" with your Conviva customer key
const convivaClient = new ConvivaClient("YOUR_CONVIVA_CUSTOMER_KEY");
convivaClient.initialize(Conviva);

Step 2: Configure THEOplayer

Next, you need to configure your THEOplayer instance to use the Conviva integration. You can do this by calling the applyConvivaContentMetadata method on your THEOplayer player instance and passing a ConvivaConfiguration object that defines the required metadata. For example:

// Replace "YOUR_THEOPLAYER_INSTANCE" with your actual THEOplayer instance

const convivaConfiguration = {
  viewerId: "unique_user_id",
  streamUrl: "http://your-video-stream-url.com",
  assetName: "TheoPlayer Video",
  applicationName: "Your Application Name"
};

YOUR_THEOPLAYER_INSTANCE.applyConvivaContentMetadata(convivaConfiguration);

Step 3: Report Playback Events

Finally, you need to report playback events to Conviva as they occur in your THEOplayer instance. You can do this by listening to specific THEOplayer events and calling the appropriate ConvivaClient methods. Below is an example of reporting a playback start event:

player.addEventListener('play', () => {
  // Replace "YOUR_THEOPLAYER_INSTANCE" and "YOUR_RESOURCE" with the actual values
  convivaClient.reportPlaybackRequested(YOUR_THEOPLAYER_INSTANCE.id, 'YOUR_RESOURCE');
  convivaClient.reportPlaybackStarted(YOUR_THEOPLAYER_INSTANCE.id, 'YOUR_RESOURCE');
});

Configuration

The THEOplayer Connector for Conviva can be configured using the ConvivaConfiguration object. Below are the available configuration options:

  • viewerId (required): Unique identifier for the viewer. It can be an anonymous, persistent user ID.
  • streamUrl (required): The URL of the video stream being played.
  • assetName (required): The name of the video asset.
  • applicationName (required): The name of the application or website hosting the player.
  • custom (optional): Custom metadata properties to send to Conviva for additional context.

API

The THEOplayer Connector for Conviva exposes several methods to interact with the Conviva integration. Below are the available methods:

  • initialize(Conviva: object): void: Initializes the Conviva client with the Conviva JavaScript library.
  • reportPlaybackRequested(playerId: string, resourceId: string): void: Reports a playback requested event to Conviva.
  • reportPlaybackStarted(playerId: string, resourceId: string): void: Reports a playback started event to Conviva.
  • reportPlaybackPaused(playerId: string, resourceId: string): void: Reports a playback paused event to Conviva.
  • reportPlaybackResumed(playerId: string, resourceId: string): void: Reports a playback resumed event to Conviva.
  • reportPlaybackEnded(playerId: string, resourceId: string): void: Reports a playback ended event to Conviva.
  • reportPlaybackError(playerId: string, errorMessage: string): void: Reports a playback error event to Conviva.

Examples

Below are some examples of using the THEOplayer Connector for Conviva in different scenarios:

Example 1: Basic Integration

In this example, we integrate Conviva analytics with a basic THEOplayer setup:

// Replace "YOUR_CONVIVA_CUSTOMER_KEY" with your Conviva customer key
const convivaClient = new ConvivaClient("YOUR_CONVIVA_CUSTOMER_KEY");
convivaClient.initialize(Conviva);

const config = {
  license: "YOUR_THEOPLAYER_LICENSE_URL",
  libraryLocation: "https://cdn.mytheoplayer.com/7e89f744-c7e1-4457-9342-eb22e5627761/THEOplayer.js"
};

const player = new THEOplayer.Player(document.getElementById('player'), config, () => {
  const convivaConfiguration = {
    viewerId: "unique_user_id",
    streamUrl: "http://your-video-stream-url.com",
    assetName: "TheoPlayer Video",
    applicationName: "Your Application Name"
  };

  player.applyConvivaContentMetadata(convivaConfiguration);

  player.addEventListener('play', () => {
    convivaClient.reportPlaybackRequested(player.id, 'YOUR_RESOURCE');
    convivaClient.reportPlaybackStarted(player.id, 'YOUR_RESOURCE');
  });

  player.addEventListener('pause', () => {
    convivaClient.reportPlaybackPaused(player.id, 'YOUR_RESOURCE');
  });

  player.addEventListener('playbackSeeking', () => {
    convivaClient.reportPlaybackResumed(player.id, 'YOUR_RESOURCE');
  });

  player.addEventListener('ended', () => {
    convivaClient.reportPlaybackEnded(player.id, 'YOUR_RESOURCE');
  });

  player.addEventListener('error', () => {
    const errorMessage = 'Playback error occurred';
    convivaClient.reportPlaybackError(player.id, errorMessage);
  });
});

Troubleshooting

If you encounter any issues or have questions about the THEOplayer Connector for Conviva, refer to the following resources:

  • FAQs: Check out the frequently asked questions for quick answers.
  • Support Page: Visit our support page to get in touch with our team.
  • Community Forum: Join our community forum to discuss with other users and experts.