HomeGuidesChangelog
Log In
Guides

API response structure

Suggest Edits

📘

Commerce Video is in Beta

The documentation and features are likely to change, and the product might contain bugs.
Please report any issues and check back for updates.

Response elements

All formats share the same API response structure, which is described below:

Status

Type: string

Values: OK(for successful responses) or an error type.

In case of an error, an array will be added to the response with the list of applicable error message(s), such as: Missing required parameter x

Placements

Type: array of placement objects

Each placement name is used as a key, like for example: viewCategory_API_desktop-Video.

The value of each key is an array of ads. Each ad has the below properties:

  • format: indicates which format is returned.

  • products: is a list of SKUs that are included in the ad format, along with additional metadata about each SKU (image, product URL, parent SKU ID, etc.)

  • products_order: some real time product substitutions are allowed based on availability of SKUs:

    • products: an array of product IDs. The order of products returned by Criteo should match the order of SKUs displayed on the site, unless a SKU is unavailable or out of stock.
    • isMandatory: If true, the overall ad unit should notbe displayed if this product is not available. If false, the ad can be shown, but the button/product tile should be removed from the unit.

Rendering

  • rendering: format-specific properties to use when rendering the ad, including image assets, colors, and custom labels.

⚠️

All video parameters in the rendering section must not be used to render the video format. Please refer to the table below for more details.

Criteo reserves the right to delete these video values at any time in the future.

📘

Video formats

Please refer to the format specifications (in the Ad rendering section) for more information on the rendering capability. You will also find in this section the Commerce Video Spotlight specification..

Please refer to the TagVideoVAST field described below.

TAGVideoVAST

  • TagVideoVASTor XmlVideoVAST:

    • TagVideoVAST (by default) : a URL to load a VAST XML via a video player that supports VAST;
    • XmlVideoVAST (if retailer opt-out of doing an extra API call to retrieve the VAST definition): The VAST XML to provide a video player that supports the VAST standard.

  • OnViewBeacon, OnLoadBeacon, OnClickBeacon, etc.: the beacons to trigger/fire back to Criteo when specific actions take place. See the section for further information.

Example

View of the API response structure

View of the API response structure


Product beacons

"OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=s8ly6TMLiDfPTKFfXm_9jzkwZuAATAS9FwGwUZ5NvnDY6LnNvBC-8AFQtntlkS50apl_jVhQvRg0-u3hWpur4RF0HikgBSOlggUUkzoK6gg9E7yC-eas9rFlwoxTuvObWpo4Yv0uedvzqBKRk-BQgcCsPHzIURbtCi_Uf5InvFyWoUkbah_XRajDvrj7oLrV-RjcYeixGYTcBoi89hqLhak5FB7_2zPWNAZMVPUCw23MNX4t0OC70fDyIL68g7RUGtBtrVvbMkMafb30uMp_L1WlmSeGHdM-EP6aUYjKRS0VBwwZkaVStkauo1XrT5-dwiyB8zm2AlAVk0AwGMNdmFlCBac-MQWycvgjgOWm-p7cGLVi5Fq3gIrUGVI5Jqq&ev=4",
"OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=MrPLtLUJfBxGX1zJk2imKaKpINZcbhVh4D9KELEKwSgdZe8-YiW50o4eQvi4SQGyvk-qeuvO1GZCJkmhfpBHJYoxcNaFwMFqtBLjax-lgCevbaCxmjOQjxqFgBXAG0CAvZx4klriBNrRrVXKIk2NI8-jpplFURhS_hDuGcMgUICraKi4wi7x958r0VNKA7iE6f-N2yyQWLlILI4yNFgqZPp_0sP-b2ks72ZdxeiJQbDko0FVMJYPClVooJPRXBWJjOvph2OOrZyh0tY4LwGp6D2p8W_rD_5HN94RR5Cewl8ojB6WFjoq_PAaJGPptLjEUV9kx-EUMFhve6vGfAlHeJ7P-ILh44mp8nOKyIsoLSIwR9HYhghChXJ4M-3EVAs&ev=4",
"OnBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=mlh4P3Tin3uct-JUxYugi37w__lZ0FOoCZ06TrhlXtQKc2faGpFFiK6g4zKwyFmd2NwXBMhVZGVtFK5T9e9KvdteZRrqZxcVW08Y9i8ecjt9m1DbEQunU8uMblAIF8yZ3bqjt71Niurwrzm-iiF-B2av8zEd0lj-Lt5AGeX1dgyP3jJdO-5Ddmw6-H5L9JTAksWT8QWbKoVwOQtwYU8r2M4yzpCGGvcvvwu6QdoC_GCfazwEsIRt446HA0AVqOwss26id8ZDjTSrwbOjSVMu5JS92mGU_3wR3Fyb2w5M8AJcLUlIXTD8oaLc9CFyAQQrbkurtKsHFPfNWRyuZOxnZr0FgSgRvHIi55eP-yr5usr4of31iaYPQvKrdTbGiEX&ev=4",
"OnWishlistBeacon": "//b.us5.us.criteo.com/rm?rm_e=F--9mZ6kqtpHdJjjowDoZJixm4BjF12sLm6qFd0fCcnunZ1oT-owxZowTezzt4Je3Q7MQiLTAyZNVlB7v-feDJHnczt4q-f43SEE67RxRFL-PWGl4jCW7F7CKBZ5WNMxBmU0eC4d88xec7diCgp-Ifhgs-Qp135jF8-BrQ7kVj9RlRan2QTtLKxCXTytdydHRhwaAsdCyOA-VStX4ZNRI297WGRTXfRepsCLAr6E5DTDdoccag4lx5v_LSUNO82i0D11y5O3xqs1QSKCIANY802UBDPdV89lEqbofgL1Gp7CYd0OSxM_545fzsFVA2RWG4ufFDIF71aXrbKhZuRencstNQ8xMWH0KMKACEk7DQWE9WObogGMEaoSf8t664O&ev=4"

Placement / Format beacon

Placement and format beacons will typically be right under the TagVideoVAST:

"OnLoadBeacon": "//b.us5.us.criteo.com/rm?rm_e=OvODs4ECUFFfQHTXDM5FiIOKZruyseTgpUr_Xt4DVTUPBoNNtG8VsH3Jo21jPK_hMV6-9I89Az0ZP2H8yslVjFaeW_HqR0Tee4gUCZ-aJMGxpkz2bjGguRcAv-jd9ocPs2HOgk24DtDHJ_D4MJJ1b0I2bILdRCp2AyfGmrj1acfyvMqngJeS4eWiDOYOkNTaYmd0uIo3bAcGObFt4DALVQE-AJXUhBjo3lyY6Kcn7n6xS1bAkK_kqT6sBtSk2KRmX_dPNKucLowpkgsRwpr-XgfcmV1VVvkCH8uXbmYbEPTQVE103_4r7zHgvpZaiU8qbROlMwCHVqvx-aY1tNuDKa0uwoqyCm6JHC2yTo06XfnqZhJphbc50hjGbPZHa24ZAdMq7bBr3G9YpxycnMQ_B-7zyNFQeSNH_M_pYAgIvo6eXjgAYA376LoJostZTGhmEEKUvgrY-7hbU_ezG5D2_BCA7Yh2xkDQHmERLd4FgWyUxcSlkksvUmIlpd1S5-b&ev=4",
"OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=qjke4FNkDL1z46EuOhojBxciTQ6Xp09cJDentgGUVT0kah-rPIHg9DUOFugsUOiCrUvFnJtuj5yYXehZp5-Ryvzf5WLl9gmin_wz4ekX7Fu_ePZKpnpNgyBBR-1Jjuqzdvkq6aIktA4r5HGzyyPF9TQDrrhYgmldAW8QYjfTk6WiI7jlZmUZnIvVah3HJi4I6QzTCTTwRXBJrFNYgJKgt2M419DkJA1UyGsnCmld5E-q4Ms3znTBEIF4fgVj6ExNAM1O_HgmgcKrDYCpo9ZVkd037dHoDiYiZVfmymlSIcubD73ZB_sBl20rsUxIujMsbLt3jliMFEthtJ8oZ3mL5Ax2HwOA2Qm58M0InNlmQf88ulFpw_IWYI6iklgleE3GrvqHb-eNj7Fg77qvKRYrHmE1gLF66WVjyactaWqP0RsIpqcAGlrjHTI7I_lQxE6&ev=4",
"OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=xt13W_TJWbSrXdNa2RG3qhZiHotcnySWD0gLaHC_PbIZyrh_V_zxUVBnIP66uaFp58Y8R0Q6ALpYjkAac-2iecIRrcEVriwqPrGkjbDFHjBsGPD4q0JTEH1mZrp2oMndYCXQEOQjAzDIBR4e52DU-koOXViZcXi9_S-bLmQA_PFop4u0ilGtfJ2AJeCOtwyNnluCwE3INkF1AEN4HqMnOgtiHcm00o9DojZemXKd_B-4bRl3eRmFR_s0jVRjwbAYHegtP7WKujHi5iRiBYogpOpVhMCkg3DciZZpza9IcBxsQVgEonlADyJYzUtvEzMZpzBE1_x6NyjUPECJUSHrxvzSI7UKgPwSukP5sCvSxY6AFqTIXXHCXKjJKFH2uQwsvi0VtHobEv_c13tm3QaIg&ev=4",
"OnFileClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=3wgFCc5lMY0fItQj4jiSm37070kK2zoFJlbFRWEZd3CB9_0DjnEp1Iq7Q1xG5mTffdi1SAarVTiAILArYOPRbbyiJ3eB_t4Y29BWqAhUbIrP6nAFT0W2DxVbOdlRLFYoISPpbV-EhVsA-oh9kXPKSk53p7w1MZAm9LS45SVZ_tZQh7-SPz2MLF4hoJGteus6hkWyfsVbgTym2gpu7JobVmaFLGrc8CyymYkfH5Xf1JKiGeNa2ZPsQtZxpnt1Dzl4Bm_BAfKYjQZnOCyWt6peHIN-azNeYwe34M9H85x1SWn5y_PKpIQZYiB_1YvdBac2VSrkBqO6SO1OgB2NiveM923Ew4Npm2rgUYUZ5bjvgL3KufQJK4FucRbvjAxEQJS&ev=4",
"OnBundleBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=FSx1IlEiuPZ8UZ6-SLMpMc_icIPoxT57Ozjvievjn-9la70L5yC5VtSagxSUpBlat4BEQLu8hrqXDcNY8kUTLylv7fdvT2B7x-NkYCfYEGZZj1lJdRLhQxckVsgIk-PyjILwpnwEODcV1wvMmXnFH5ttrA5iSp847tgW-2fvZxS1w7YX30tbLYvAmZTvJxPnOXKPcmwnJz3BJ6d8CMLgdVoJN67AtgRKTpkb1s0eYk-ANM_gv7cgtEME2142W8vlv6-NayvCwGvw_CtH-OWVZoEJ52TJMMbj3Aa6jPHBRgw9P-LVsFWY3f_kxauVNl7mHTAyVvajrcPeYl7_8ygq6hFtqm9IBryXB8iMctEXDronoGT-VHfrAqet9nVvPYMyATWjm-X21M88YLAGoaDuQ&ev=4",

Rendering Fields

Below is an example of rendering fields in the API response:

"rendering": {
  	"background_video": "{\n  \"url\": \"https://static.criteo.net/design/dt/commerce_max/retailer_06/d97eb13b8e3d496eaddef7b4c998d286_video.mp4\",\n  \"width\": 720,\n  \"height\": 1280,\n  \"duration\": \"00:00:06\"\n}",
  	"video_caption_file": "https://static.criteo.net/video/onsite_cc/laptop_vertical.vtt",
  	"video_alt_text": "Laptop",
  	"border_color": "#712329",
  	"video_optional_redirect_url": "https://www.retailer.com/shop/search-results.html?q=laptop",
  	"video_optional_redirect_url_app": "",
  	"video_media_files": "[\"background_video\"]"
},

Below is the description of the API response fields for format rendering within the page.

⚠️

These fields are subject to change based on the video format.

FieldDescription
video_background (including all information within this field)Do not use this field. It is reserved for Criteo purposes only. All video-related information, assets and tracking must be used from the VAST XML only.
video_caption_fileThe video caption file (WebVTT)
video_optional_redirect_url video_optional_redirect_url_appDo not use these fields. It is reserved for Criteo purposes only. The optional redirection link to a landing page if the user clicks on the video player is available in the VAST definition (cf. <ClickThrough> node). As only one redirection link is supported in VAST, Criteo will automatically return the right URL based on the page requesting ads.
alternative_text / background_video_alt_text (or equivalent naming)Text to display in an alt_text div attribute for WCAG compliancy purposes.
video_media_files video_firework_id video_caption_file video_captionsDo not use these fields. It is reserved for Criteo purposes only.

Updated 3 months ago

What’s Next