Please report any issues and check back for updates.
Introduction
This document aims at providing a detailed guideline about implementing On-Site Commerce Video ads on mobile platform, for iOS.Video Player Implementation Guide
When it comes to building your video ad implementation, there are a few high-level steps to consider:- Requesting and parsing the VAST tag,
- Creating the video player, that will show the ad,
- Setting up an ad session,
- Firing beacons at the proper time during video playback,
- Finishing the ad session,
- Handling closed captions.
Step 1: requesting and parsing the VAST tag
To obtain the data for your video player, start by fetching the VAST information from the Criteo API Ad Response. Here is an example of how to request the VAST file (if required) and how to parse it, using XPath, to retrieve:- The link of the video media files,
- VAST XML tracking beacons,
- OMID Verification URL and
VerificationParameters, - Closed captions file.
Step 2: creating the video player
UIKit, the traditional approach for building user interfaces using interface builder and View Controllers. If you are using SwiftUI, please refer to this Apple documentation to integrate UIKit views and view controllers inside SwiftUI views.AVPlayer which offers methods like play(), pause(), along with properties such as: volume and duration to help us interact with the video player. To follow the video player specifications, we incorporate button control elements for Play/Pause , Mute/Unmute and to Enable/Disable CCs (close captions) with click listeners.
Additionally, be aware that local regulations may require a callout or pop-up for mandatory notices.
In practice, we add a UIView called playerView for the player container in the interface builder. This view will also be associated to the ad session and interact with the OM SDK.
The video player can be created programmatically, and added to this container.
AVQueuePlayer and AVPlayerLooper so the video ad loops infinitely instead of a simple AVPlayer. We also start the video muted by default, setting the isMuted property to true.
The media asset can be created with let asset = AVAsset(url: localVideoURL). For creating a media asset with closed captions, see the section below.
Step 3: setting up OMID ad session
Clients must support OMID to enable their player to run additional scripts, hence allowing Criteo to track video viewability. This allows Criteo to send its own verification script within the VAST XML to track video viewability.AdVerifications element where these verifications reside. Each verification element nested inside AdVerifications details the resources needed for verification.
- Load the OMID service script,
- Create an ad session configuration and the ad session itself,
- Register the player showing the ad and start the ad session,
- Trigger
adEvents&mediaEventsevents to OM SDK when Video & Ad related events occur.

Level | Beacon name | Description |
|---|---|---|
OMID ( |
| Indicates that the OMID Ad session was properly initialized. |
OMID ( |
| Indicates that the video just started, and the video is displayed 100% in the viewport. |
OMID ( |
| Indicates that the video just reached the 25% quartile, and the video is displayed 100% in the viewport. |
OMID ( |
| Indicates that the video just reached the 50% quartile, and the video is displayed 100% in the viewport. |
OMID ( |
| Indicates that the video just reached the 75% quartile, and the video is displayed 100% in the viewport. |
OMID ( |
| Indicates that the video just completed, and the video is displayed 100% in the viewport. |
OMID ( |
| Indicates that the video was playing for 2 consecutive seconds, and the video is at least displayed 50% in the viewport. Note that, buffering the video or pausing, will reset the 2 seconds counter. |
VAST XML - OMID |
| Indicates that the verification script failed to initialize. |
1. Load the OMID service script
The provided IAB OM SDK is composed of a script (omweb-v1.js) and a mobile library that need to be included for the creative to support viewability.
omweb-v1.js is the OMID JS library for the web context.2. Create an ad session configuration and the ad session itself
Before the ad session initialization, the OM SDK needs to be activated. The ad session also requires specifying some parameters related to the Criteo integration.VerificationScript , VerificationParameters and VendorKey are provided inside the VAST.3. Register the player showing the ad and start the ad session
When the ad session is started, the Criteo verification script is automatically loaded. At this point, the Criteo verification script will start observing anyAdEvents & MediaEvents that are triggered toward the OM SDK.
4. Trigger adEvents & mediaEvents events to OM SDK when Video & Ad related events occur
AdEvents & MediaEvents is accessible on IAB’s Github.- Criteo will be able to track quartile events (if the video is 100% part of the viewport)
- Advanced events are computed to track if 50% of the video is playing & displayed in the viewport during 2 consecutive seconds.
AdEvents & MediaEvents must be triggered aside of the existing tracking beacons for quartile & display events. Additionally, the video buffering events must be triggered.
Triggering OMID events is similar to triggering VAST trackers, both will be described in the following section.
Step 4: firing beacons during video playback
Once the creative is downloaded, we can start the OMID session and trigger theloaded event.
impression beacons from VAST and to OMID.
start, firstQuartile, midpoint, thirdQuartile and complete beacons are managed in a function triggered by a polling thread. For each of their playback events, we send both VAST and OMID beacons.
Tap Gesture Recognizer in the Interface Builder which is linked to the playerView and triggers a clickHandler action in the Controller. In this function, we send the OMID and VAST click beacons and instruct the browser to open the URL from the VAST tag, only if a redirection URL is provided.
If the redirection URL is not provided, we pause/resume the video and trigger the corresponding tracking beacons:
UIView, it checks and sends the percentage of the video being visible. So, if the buttons are on the overlay of the player, make sure to declare them:Step 5: finishing the ad session
It is important to handle correctly the destruction of the player and the ad session:Extra: Handling closed captions (CC)
Instead of creating aAVAsset using only the video URL, we are creating a AVMutableComposition with 3 tracks:
- one for the video,
- a second one for the audio,
- and a third one for the captions.
AVMutableComposition only supports the insertion of locally stored assets; remote items cannot be used. As a result, we download and store the media file and closed captions locally before initializing the player.