Skip to main content
Hidden pageThis page is currently hidden in Criteo’s documentation. This means it won’t appear in the navigation menu and is only accessible with the link. To return to this page in the future, please make sure to bookmark it.
Commerce Video for Apps is in BetaThe documentation and features are likely to change, and the product might contain bugs.
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.
Android vs iOSThis page only covers the video player implementation for iOS. Please refer to this page for the Android implementation.
App vs web (desktop & mobile)This page focuses on mobile app implementation. For a broader context, please visit the video player implementation guide for web.
Version requirementsFor iOS, the minimum iOS version supported is 9.0, but you can choose to support the latest 5 versions.

Video Player Implementation Guide

When it comes to building your video ad implementation, there are a few high-level steps to consider:
  1. Requesting and parsing the VAST tag,
  2. Creating the video player, that will show the ad,
  3. Setting up an ad session,
  4. Firing beacons at the proper time during video playback,
  5. Finishing the ad session,
  6. Handling closed captions.
Criteo supports VAST 4.2 (the IAB specs are available here).

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.
And the parsing function to evaluate the XPath below:

Step 2: creating the video player

UIKit vs SwiftUIOur iOS example for the video player is built with 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.
Our video player is built with the native componentAVPlayer 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.
We use an 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.
About OMIDThe Open Measurement Interface Definition (OMID) is a standardized technology provided by IAB to measure and verify the viewability of digital ads, particularly video ads, across various platforms and devices.OMID provides a consistent framework for measuring viewability metrics, such as viewable impressions and viewable video plays, in compliance with industry standards. Implementing OMID offers accurate insights into ad performance and user engagement, and is also used to track video viewability the same way across all retailers, ensuring coherence across networks.OM SDK in this documentation refers to the OM SDK for mobile platforms (iOS).
Section 3.16 of the VAST specification outlines an optional AdVerifications element where these verifications reside. Each verification element nested inside AdVerifications details the resources needed for verification.
The Open-measurement SDKTo handle these resources, we pass them to the Open-Measurement SDK provided by IAB. The official OM SDK implementation guide for iOS can be found here. The documentation provides full code snippets for each step to integrate viewability.
At a high level, the process goes as follows:
  • 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 & mediaEvents events to OM SDK when Video & Ad related events occur.
The IAB implementation guide is not complete enough to cover all the Criteo video player specifications. For that reason, it is highly recommended to also verify your integration followingthe IAB documentation for iOS. with the Criteo verification script.
The Criteo verification script comes from the VAST XML file.
Through the OM SDK, several events will be emitted by Criteo OMID Verification Script to Criteo servers:

Level

Beacon name

Description

OMID (VerificationParameters)

omidTrackView

Indicates that the OMID Ad session was properly initialized.

OMID (VerificationParameters)

start

Indicates that the video just started, and the video is displayed 100% in the viewport.

OMID (VerificationParameters)

firstQuartile

Indicates that the video just reached the 25% quartile, and the video is displayed 100% in the viewport.

OMID (VerificationParameters)

midpoint

Indicates that the video just reached the 50% quartile, and the video is displayed 100% in the viewport.

OMID (VerificationParameters)

thirdQuartile

Indicates that the video just reached the 75% quartile, and the video is displayed 100% in the viewport.

OMID (VerificationParameters)

complete

Indicates that the video just completed, and the video is displayed 100% in the viewport.

OMID (VerificationParameters)

twoSecondsFiftyPercentView

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

<Tracking event=“verificationNotExecuted”>

Indicates that the verification script failed to initialize.

The 100% in the viewport display is an industry standard to track playback events such as quartiles. The two consecutive seconds and 50% display in the viewport is an MRC standard.

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.
The script can either be self-hosted or pulled from Criteo’s CDN, where we host copies. The file can be found on this page.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.
OMID 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 any AdEvents & MediaEvents that are triggered toward the OM SDK.

The complete list of available AdEvents & MediaEvents is accessible on IAB’s Github.
Through those calls, the Criteo verification script will be able to compute advanced viewability events:
  • 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.
All calls to both 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 the loaded event.
Right after the ad is presented, we can fire the impression beacons from VAST and to OMID.
The 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.
To ensure accurate beacon tracking, playback beacons (start and quartiles beacons) should only be emitted once, during the first play of the video, while the video is playing.However, interaction beacons (such as click, mute, unmute, pause, and resume) must be emitted each time the corresponding user action occurs.
We handle the pause/resume beacons by attaching an event listener to the button. If the player is currently playing, we pause and emit the OMID and VAST pause beacons. Otherwise, we emit the resume beacons. We also change the image of the button to represent a play and pause button.
We handle the click beacon by creating a 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:
Finally, we handle the mute/unmute beacons similarly, by attaching a listener to the button. It changes the state of the player, the image of the button, and triggers the VAST and OMID tracking beacons.
OMID & buttonsAs the OM SDK has access to the video player 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 a AVAsset 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.
Here is the full code example:
coffeescript Swift
NotePrior to iOS 15, 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.
coffeescript Swift