> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  **Github repository**

  You can find the Criteo-owned video player repository [here](https://github.com/criteo/video-ad-player/tree/main) on GitHub.
</Info>

<Warning>
  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)](/retailer-integration/docs/video-player-implementation-guide-desktopmobile#step-4-additional-verification-with-omid-compatible-scripts-video-views) for more details.
  The project itself does not bundle or include our own OMSDK.
</Warning>

***

## Key Features

This video player implementation fully adheres to [Criteo’s official video player specifications](/retailer-integration/docs/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 the Criteo video player, showing the pause, mute, and closed-caption toggles on the right side of the screen.

<Frame>
  <img src="https://mintcdn.com/criteo-e1682996/T1671lE5Qb9IdIDU/images/retailer-integration/docs/cdfa84e333fd8957ee45a24b3f328e4f6531f0a261326030f6268bcb1c41b1c0-image.png?fit=max&auto=format&n=T1671lE5Qb9IdIDU&q=85&s=76b87c032264c1bffed82fbbefd8a6ae" alt="cdfa84e333fd8957ee45a24b3f328e4f6531f0a261326030f6268bcb1c41b1c0 image" width="765" height="428" data-path="images/retailer-integration/docs/cdfa84e333fd8957ee45a24b3f328e4f6531f0a261326030f6268bcb1c41b1c0-image.png" />
</Frame>

***

## 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

<Info>
  For implementation details and the full list of available configuration options, see the
  [source code on GitHub](https://github.com/criteo/video-ad-player/blob/main/src/index.ts).
</Info>

**`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, OMID script paths, error callback. You can view `VideoOptions` definitions directly in [the source code on Github](https://github.com/criteo/video-ad-player/blob/main/src/components/video/video.tsx).

**onError Callback**

The `onError `callback is invoked whenever the player encounters a failure while loading the VAST, playing the video, or finding the target element on the page.

It receives a `VideoErrorInfo` object that explains where the error came from and what happened, so you can decide how to handle it when something goes wrong. See the `VideoErrorInfo` interface in this page for a list of the properties provided to the `onError` callback.

***

## Demo

The `examples/` directory [here](https://github.com/criteo/video-ad-player/tree/main/examples) 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:

```bash theme={null}
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:

```javascript theme={null}
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

```javascript expandable theme={null}
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 (
    &lt;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"
    }}
    /&gt;
  );
};
```

***

<br />

## What's next

* [Video player implementation (App: iOS)](/retailer-integration/docs/video-player-implementation-app-ios)
* [Video Player Implementation (Web Browser)](/retailer-integration/docs/video-player-implementation-guide-desktopmobile)