Criteo-Owned Video Player Integration

Purpose

This guide explains how to integrate the Criteo-owned video player into your website to serve video ads within web applications.

It handles the technical details of parsing VAST ads and managing video playback, supports accessibility features such as keyboard navigation and closed captioning, and includes OMID integration for accurate ad viewability tracking according to industry standards.

📘

Github repository

You can find the Criteo-owned video player repository here on GitHub.

⚠️

Per Legal’s guidance, this project does not redistribute the Criteo-hosted OMSDK. Retailers must download and host their own instance of the OMSDK separately.

Please refer to Step 4 of the Video Player Implementation (Desktop/Mobile) for more details. The project itself does not bundle or include our own OMSDK.

Key Features

This video player implementation fully adheres to Criteo’s official video player specifications, as demonstrated by the key features listed below:

• Public API for easy player bootstrap and integration
• VAST ad parsing to extract media files, clickthroughs, tracking beacons, and ad verifications
• Auto play/pause on scrolling & mute by default
• Automatic video selection to match target dimensions for optimal playback quality
• Robust ad event handling with impression, click, and quartile tracking
• OMID SDK integration for accurate viewability and engagement measurement
• Closed caption support with precise WebVTT timing
• Lightweight inline SVG icons for UI elements

Video Player Example

Below is a screenshot of a video player example, with CTAs displaying on the right of the screen.

Tracking Events

During the initial playback, the player automatically emits VAST tracking beacons for the following events:

• impression
• start
• firstQuartile
• midpoint
• thirdQuartile
• and complete

Additional events such as mute, unmute, pause, resume, and clickThrough are fired in response to user interactions.

Main Components

📘

For implementation details and the full list of available configuration options, see the source code on GitHub.

criteoVideoPlayerFromUrl(vastUrl: string, elementId: string, options: VideoOptions):

This is the primary function you'll interact with. It serves as a complete wrapper that handles all aspects of video ad integration, from VAST parsing and asset downloading to OMID measurement and state management. It provides a simple API while managing the complex interactions between network requests, video playback, and ad tracking behind the scenes.

criteoVideoPlayerFromContent(vastContent: string, elementId: string, options: VideoOptions):

Similar to criteoVideoPlayerFromUrl, but accepts a VAST XML string or object directly instead of fetching from a remote URL. Use this when you already have the VAST content available in your application.

Both components also accept an options object (of type VideoOptions):

This object defines a set of configurable properties for customizing player behavior, such as dimensions, captions, alt text, and OMID script paths. You can view VideoOptions definitions directly in the source code on Github.

Demo

The examples/ directory here provides example implementations for both criteoVideoPlayerFromUrl and criteoVideoPlayerFromContent.

Check out the README.md file in each folder for installation instructions.

Quick Start

Install Criteo Video Player from NPM:

npm i @criteo/video-player

Vanilla JavaScript Example

This example demonstrates how to initialize the video ad player in a plain JavaScript environment, without any framework:

import { criteoVideoPlayerFromUrl } from "@criteo/video-player";
import "@criteo/video-player/dist/style.css";

await criteoVideoPlayerFromUrl(
    "https://example.com/adtag.xml",
    "video-player-container",
    {
        sessionClientUrl: "https://example.com/omid-session-client.js",
        omWebUrl: "https://example.com/omweb.js",
        altText: "Criteo Video Player",
        targetDimensions: { width: 640, height: 360 },
    }
);

React JavaScript Example

import { criteoVideoPlayerFromUrl } from "@criteo/video-player";
import "@criteo/video-player/dist/style.css";

const CriteoVideo = ({vastUrl, elementId, options}) => {
  const containerRef = useRef(null);
  const idRef = useRef(elementId);

  useEffect(() => {
    if (!vastUrl || !containerRef.current) return;
    const currentEl = containerRef.current;

    criteoVideoPlayerFromUrl(
        vastUrl, 
        idRef.current, 
        {
            altText: "Criteo Video Player",
            ...(options || {}),
        }
    );

    return () => {
      if (currentEl) currentEl.replaceChildren();
    };
    
  }, [vastUrl, options]);

  return <div id={idRef.current} ref={containerRef} />;
};


const App = () => {
  return (
    <CriteoVideo
        vastUrl="https://example.com/adtag.xml"
        elementId="video-player-container"
        options={{
            sessionClientUrl: "https://example.com/omid-session-client.js",
            omWebUrl: "https://example.com/omweb.js"
    }}
    />
  );
};