Deploy Video Sensor — Conviva Docs

Instrument your video app with the Conviva Video Sensor to stream real-time playback, ad, and error telemetry into Pulse — from first install to production launch.

Introduction

The Conviva Video Sensor is a lightweight library that you embed in your video application. It observes the player as it runs and reports what the viewer actually experienced — every stream start, rebuffer, bitrate shift, ad break, and failure — as a continuous session to Conviva's real-time analytics platform.

The sensor listens to player events and reports them, alongside the metadata you attach, so that every session in Pulse can be sliced by content, device, CDN, geography, or any business dimension you define.

What the sensor collects

The sensor reports two things: player events as they happen, and the metadata attached to each session. Metrics such as video start time, Connection Induced Rebuffering Ratio, Exits Before Video Start, and concurrent plays are not measured in your app — Conviva derives them server-side from these events. Review the full list of metrics powered by the events collected by the sensor.

Events

Session lifecyclePlayback requested (which opens the monitoring session), playback ended, playback failed, and playback errors reported as either fatal or warning.

Playback statePlayer state changes (playing, buffering, paused), seek start and end, play head position, current buffer length.

Stream qualityPeak and average bitrate, rendered frame rate, dropped frames, CDN IP address, and audio, subtitle, and closed-caption language.

AdsAd break start and end, ad loaded, ad started, ad ended, ad skipped, ad failed, and ad errors — plus the same state and quality events on the ad session.

App & user actionsUser wait start and end, app backgrounding and foregrounding, network connection type, and any custom application events you choose to report.

Metadata

ContentAsset name, stream type (live or VOD), player name, viewer ID, stream URL, default resource, duration, encoded frame rate, content type, channel, brand, affiliate, category, series, season, episode, and genre.

AdAd technology (client-side or server-side), ad position (pre-, mid-, or post-roll), ad ID, ad system, creative ID, ad stitcher, slate indicator, wrapper first-ad details, and ad asset name, stream URL, and duration.

Device & appDevice category and type, brand, manufacturer, model, OS name and version, screen resolution and scale factor, application version, and player framework name and version.

CustomAny key/value tags you define to map Conviva data onto your own business dimensions. Find the tags to implement under Setup Metadata in Application Manager.

How much you report depends on your player. Where a Conviva module exists for your player, most playback events and several metadata fields are autocollected — an ExoPlayer or AVPlayer integration picks up player state, bitrate, seek, and buffering on its own. Custom player integrations may require explicit reporting of events and metadata by your player application. Each platform's Constants and Metadata page lists exactly which fields are autocollected and which you must set.

How the sensor is packaged

Conviva video sensors ship as core SDKs plus optional player modules, ad modules, and plugins across a wide range of platforms. For popular players and ad frameworks, the module handles event mapping for you — you pass Conviva a reference to the player object and the module reports events automatically. For players with no module, you implement the sensor with core SDK APIs and report video and ad events and metadata explicitly. Both paths produce the same metrics.

Before you start: get your CUSTOMER_KEY

Every integration begins with a CUSTOMER_KEY. Conviva provisions two accounts — one test, one production — each with its own key. Find yours under Account Info in Pulse. Integrate and validate against the test key, then swap to the production key at launch. Contact your Conviva account team if you can't access it.

High-level architecture connecting a video application, the Conviva Video Sensor, and Conviva's real-time analytics platform

Plan, Integrate, Validate, Launch Process

Getting started is simple. Conviva ships out-of-the-box modules for most popular players, so for a supported player you can add the SDK, pass in your player object, and be monitoring the same day.

The four phases exist for what comes next. Every app is different — a different player, a different ad stack, a different idea of what a "show" or a "channel" is. These phases are how we make sure that difference shows up as clean data: metrics you can trust and metadata that maps to your business, from the first day of real traffic rather than the third revision.

The payoff. Four short phases, one outcome: every metric correct and every tag consistent across all your apps — so the numbers in Pulse are something your teams can act on.

Expand a phase for who leads it and what it involves.

PHASE 1

Planning

Metadata strategy

Kick-off

Integration workshop

Led by Conviva account team

PHASE 2

Integration

Leverage tools

Instrument the player

Report metadata

Led by your dev team

PHASE 3

Validation

Self-validation

Fix and re-test

Led by your dev / QA team

PHASE 4

Launch

Deployment

Pulse data

Support handover

Led by your deployment team

PHASE 1PlanningMetadata strategy · kick-off · integration workshop

Led by the Conviva account team, with your key stakeholders.

Why this phaseDecide once what you want to measure, so every app tags it the same way. Half an hour of agreement here is what makes your data comparable across platforms later.

The Planning phase is led by your Conviva account team to make sure both sides are set up for success. Here we confirm key stakeholders, technical scope, timeline and prioritization, and metadata strategy — all signed off before integration begins.

Metadata strategy

Mapping your business needs to metadata tags is your metadata strategy, and it forms part of your business acceptance criteria. A successful implementation passes the correct tags to Conviva while fulfilling those needs. For example, to measure Quality of Experience (QoE) differences between live content and Video On Demand (VOD) content, you must pass a tag identifying whether the content is live.

Metadata splits into required tags, which power Conviva product use cases, and custom tags, which serve your unique business needs.
Metadata must be structured uniformly and consistently across every integrated device application.
All properties, metadata keys, and values are case-sensitive.

Implementation kick-off

Kick-off reviews the implementation lifecycle, timelines, and priorities. We then qualify your device applications to capture the technical details and limitations that shape the integration — which determines the SDK or library each application should use. We also review Conviva metrics at a high level, sign off the required and custom metadata strategy, and share best practices for a smooth launch.

Integration workshop

Your Conviva account team organizes an integration workshop for your player and application development teams, so your developers can work directly with Conviva integration engineers and clear up open questions. Topics covered:

Integration scope and concepts
Metrics
Tools
Integration-specific use cases
Self-validation
Additional resources and environment access

PHASE 2IntegrationTools and resources · advanced use cases

Led by your application development team, supported by the Conviva account team and integration engineer.

Why this phaseIf your player has a module, most of the work is already done — pass in the player object and the events collect themselves. This phase is about wiring up the parts only your app knows: your metadata, your ad stack, your edge cases.

In the Integration phase your developers download the latest SDK or library for their platform and use the tools and resources below to instrument the application. Follow the integration steps and your platform page.

Tools and resources

Application Manager — your single source of truth for metadata strategy and device application tracking. Use it to qualify device applications and the SDK each one uses, and to capture, maintain, and export your metadata strategy.
Touchstone — available in Pulse, for debugging and self-validating the sensor integration. It tracks user actions on the integrated device and transmits session summaries, metrics, and metadata for inspection.
Pulse — Conviva's real-time dashboard for monitoring integrated device applications. The integrity of the data flowing into Pulse correlates directly to the quality of your integration.
Conviva integration instructions — per-platform detail, SDK and sample app download links, sensor API references, and self-validation material.
Network Traffic Shaping Tool — a script to simulate varied network conditions on devices that don't allow a proxy setup.
Conviva SSO — one set of credentials covers Application Manager, the Conviva Developer Community, Pulse, and Touchstone. For access to a specific c3.account, contact your internal Conviva administrator or your Conviva account team.

Advanced use cases

The SDK also covers scenarios beyond a single straightforward playback:

Reporting program changes during live or live-linear streaming
Reporting video changes within a playlist
Reporting once when playback does not recover
Reporting multiple errors caused by retries when playback does not recover
Reporting recovery from a fatal error by switching to a different asset URL or a different CDN
Reporting a warning when playback is not impacted
Handling user actions such as user dialogs, backgrounding, and foregrounding

See Advanced Use Cases for details.

PHASE 3ValidationSelf-serve — test cases, Touchstone, expected results

Led by your development and QA team · self-serve.

Why this phaseCatch a wrong tag or a missed event here and it costs an afternoon. Catch it after launch and you're re-releasing the app and backfilling weeks of data you can't trust.

Validation is self-serve. Once your integration is complete, run a comprehensive self-validation pass on each device application before you launch. Conviva publishes the full set of test cases, step-by-step instructions, expected results, and walkthrough videos so your team can confirm data integrity independently.

How to self-validate

Work through the published use cases against your build, using Touchstone to inspect each session as it happens.
Check metric accuracy — video start time, rebuffering, bitrate, errors, exits, and ad metrics against the expected results for each case.
Check metadata accuracy — every required tag present and correctly valued, custom tags matching your signed-off metadata strategy, and keys and values matching exactly (they are case-sensitive).
Cover the error and recovery cases, not just the happy path — startup failures, mid-stream errors, retries, CDN switches, backgrounding.
Re-run the affected cases after fixing any issue, and confirm the data in Pulse.

Self-validation material. Test cases, detailed steps, expected results, and sample validation videos are all on the Self-Validation Use Cases & Videos page.

Your Conviva account team and integration engineer can help with any questions that come up during self-validation.

PHASE 4LaunchDeployment checklist · support handover

Led by your application deployment team, supported by the Conviva account team.

Why this phaseFour checks separate a clean production cutover from a week of test-key data polluting your dashboards.

The Launch phase is led by your team with support from Conviva. We recommend coordinating launch dates with your Conviva account team so we can support you on launch day.

Deployment checklist

Configure the app to use the production CUSTOMER_KEY.
Confirm the app uses the standard / production client initialization.
Confirm Touchstone is NOT enabled.
Notify Conviva when the app or player will be released to the general public.

Support handover

After launch, the Conviva support team takes over your ongoing requests. If you change subsequent versions of your device application — whether the change relates to Conviva or not — coordinate with your Conviva representative in advance so the integration can be checked.

For production issues, contact support@conviva.com with your Conviva C3 account ID, integration platform, and framework.

Supported Platforms and SDKs

Conviva Video Sensor integrations leverage Conviva SDKs and player library APIs for optimized reporting of video stream events. Pick your platform below; the second column lists the player and ad modules available for it. Custom Player means you can integrate any other player on that platform using the core SDK APIs.

Android

ExoPlayer, Media3, Brightcove, NexStreaming, Custom Player Ads: Google IMA, Google DAI, ExoPlayer IMA Extension, Media3 IMA Extension, Custom Ad Manager · also available: Conviva Integration Assistant plugin

iOS / tvOS

AVPlayer, AVQueuePlayer, Brightcove, Custom Player Ads: Google IMA, Custom Ad Manager

JavaScript / Web

HTML5, Video.js, Chromecast CAF, Samsung Tizen, Trilithium, WebMAF, Chromecast v2 (deprecated), Custom Player Ads: Google IMA, Google DAI, Custom Ad Manager

Roku

Roku SceneGraph Video node, Custom Player Ads: Google DAI, YoSpace Ad Management SDK, RAFX SSAI Adapter, RAF (CSAI), Custom Ad Manager

C SDK

Custom Player — core SDK APIs for embedded and native platforms with no prebuilt module Ads: Custom Ad Manager

Rust

Custom Player — core SDK APIs for Rust-based applications Ads: Custom Ad Manager

Web Brightcove

Brightcove Player (browser)

Web thePlatform

thePlatform player (browser)

XBox One / Windows 10 — MediaPlayer

MediaPlayer, MediaElement, Custom Player

XBox One / Windows 10 — WinJS

XBox WinJS media player, Custom Player

castLabs

castLabs player — partner-maintained integration

Getting the libraries. SDK packages, sample apps, and release notes are published on each platform page above and in the Conviva repositories at github.com/conviva. A typical sensor integration takes at least 4–8 hours of development, plus self-validation and deployment testing.

Integration Steps

These are the steps common to every integration, whether you use a player module or the core SDK APIs. Platform-specific variations are covered on the platform pages linked above — use the tabs within each page to see the instructions for your player.

Install the library.
Add the SDK and any player or ad module as a dependency.
Initialize Conviva analytics with your test CUSTOMER_KEY.
Set device metadata.
Check which fields are required on your platform — Conviva auto-detects many values to keep implementation light.
Implement metadata and event reporting.
- Report the playback attempt along with metadata (content, workflow, audience, and other relevant tags).
- Pass the player object to Conviva for auto-collection of all relevant video events — or report events explicitly for custom implementations.
- Pass the ad object to Conviva for auto-collection of ad events — or report ad events explicitly for custom implementations.
- Report user actions such as backgrounding and user dialogs.
- Report end of playback.
Self-validate your integration using Touchstone — inspect sessions, events, and metadata as they happen.
Work through the Self-Validation Use Cases & Videos for metric and metadata accuracy.
Switch to the production CUSTOMER_KEY and go live.
Analyze your data in Pulse and start improving quality for your viewers.

Important. Make sure the Touchstone gatewayUrl is NOT used in production.

When to start monitoring

Start Conviva monitoring immediately after the viewer initiates playback — either by pressing play or via auto-play. Follow these guidelines:

Only once per video playback attempt.
Before requesting and connecting to the video stream.
Before any errors that could prevent playback might occur.
Before any DRM checks or other stream authentication logic.
Before playing ads.

Metadata Concepts

Conviva categorizes metadata tags into three buckets:

Bucket	What it covers
Pre-defined tags	Reported as part of the content information for every video.
Device tags	Many are auto-detected by Conviva from the user-agent string, but not all. Device category in particular is a critical key that your application is often expected to set — always so in custom integrations, and on several module-based platforms too. Check your platform's Constants and Metadata page for which device tags you are responsible for.
Custom tags	Reported to meet your specific business requirements, unique to each customer. Find the tags to implement under Setup Metadata in Application Manager.

Updating metadata, or setting it late after monitoring of the content has already started, is subject to certain limitations. See your platform's instructions for details.

Naming custom tags. Do not use the c3.cm prefix for your own tags — that namespace is reserved for Conviva's pre-defined metadata. Name custom tags plainly, for example MyCustomTag1 or my_custom_tag.