Display ads integration guide

Display Ads support two creative formats delivered through the same /v1/dsp/getBids endpoint: banner ads (JSON markup) and video ads (VAST 4.2 XML). A single request can include impression slots of either or both types.

Supply structure

FCC uses a page and slot hierarchy. A single page typically contains one or more ad slots. Send one consolidated request per page with one imp object per slot, rather than a separate API call per slot.

{
  "id": "req-001",
  "imp": [
    {
      "id": "slot-1",
      "banner": { "format": [{ "w": 300, "h": 250 }] },
      "ext": { "slotid": "HOME-PAGE-BANNER-TOP" }
    },
    {
      "id": "slot-2",
      "video": {},
      "ext": { "slotid": "HOME-PAGE-VIDEO-MID" }
    }
  ]
}

Two behaviours follow from this design:

• Deduplication: FCC processes the batch and returns globally deduplicated ads across all requested slots.
• Mixed formats: While a single request can contain both banner and video slots, separate slots are designated for each format to prevent competition.

Ad markup (adm)

Each bid in the response contains an adm field. The format depends on the impression type.

Impression type	adm format
Banner	JSON-encoded string — parse and render client side.
Video	VAST 4.2 XML string — pass to a VAST-compatible video player. See Video ads below.

---

Banner ads

The adm field for banner impressions is a JSON-encoded string. Parse it before use. For the full schema definition, see the DSP GetBids API reference.

Video ads

When the impression slot requests a video, the adm field contains a fully compliant VAST 4.2 XML string with all video details such as the ad system, ad title, impression tracking, and information about the video creative (e.g., duration and media file details).

VAST (Video Ad Serving Template) is a set of specifications developed by the IAB (Interactive Advertising Bureau) for standardizing the way video ads are tracked and served. FCC uses the VAST 4.2 XML markup schema for all video responses. Refer to the IAB VAST 4.2 specification for the full standard.

Player requirements

The client side video player must be capable of parsing VAST XML. Use a VAST-handling JavaScript library such as vast-client-js or videojs-ima.

Delivery

FCC uses progressive delivery (delivery="progressive") via single MP4 containers. The <MediaFile> element in the VAST XML provides:

• width, height — player dimensions
• bitrate — for fail-fast evaluation
• codec — e.g., H.264

The video player must evaluate the <MediaFiles> array and initiate a progressive download of the provided media asset.

Tracking

Tracking URLs are embedded within the VAST XML and must be fired by the video player. Replace FCC macros with epoch timestamps in milliseconds before firing:

Macro	Used in	When to fire
[EVENTTIME]	<Impression>	Current timestamp at the moment of the event.
[TIMESTAMP]	<ClickTracking>	Current timestamp at the moment of the click.
[STARTTIME]	<Tracking event="start">	Timestamp when video playback began.
[ENDTIME]	<Tracking event="start"> alongside [STARTTIME]	Timestamp at the moment the event is being reported.

Impression and view firing conditions

Event	Condition
Impression	Video player is at least 50% visible in the active browser viewport and the first frame has rendered.
View	Video has remained at least 50% visible for a minimum of 2 continuous seconds of active playback. Fire with [STARTTIME] and [ENDTIME] substituted.

Click tracking

Advertisers may create video ads without a destination landing page:

• With landing page: The VAST XML contains a <VideoClicks> block with both <ClickThrough> and <ClickTracking> URLs. Make the video player clickable.
• Without landing page: The <VideoClicks> block is omitted entirely. No click tracking URLs are present.

Sample VAST response

<?xml version="1.0" encoding="UTF-8" ?>
<VAST version="4.2" xmlns="http://www.iab.com/VAST">
    <Ad id="banner_id">
        <InLine>
            <AdSystem version="1.0">Flipkart Commerce Cloud</AdSystem>
            <AdTitle><![CDATA[In-Page-Video-Ad]]></AdTitle>
            <Impression id="imp_pixel">
                <![CDATA[https://{tracker-domain}/v1/dsp/tr/impression?pl=...&adType=DSP]]>
            </Impression>
            <Creatives>
                <Creative id="creative_id">
                    <UniversalAdId idRegistry="unknown">creative_id</UniversalAdId>
                    <Linear>
                        <Duration>00:00:15</Duration>
                        <TrackingEvents>
                            <Tracking event="start">
                                <![CDATA[https://{tracker-domain}/v1/dsp/tr/view?pl=...&vst=[STARTTIME]&vet=[ENDTIME]&adType=DSP]]>
                            </Tracking>
                        </TrackingEvents>
                        <VideoClicks>
                            <ClickThrough>
                                <![CDATA[https://www.example.com/landing-page]]>
                            </ClickThrough>
                            <ClickTracking>
                                <![CDATA[https://{tracker-domain}/v1/dsp/tr/click?pl=...&cet=[TIMESTAMP]&adType=DSP]]>
                            </ClickTracking>
                        </VideoClicks>
                        <MediaFiles>
                            <MediaFile
                                    id="media_id"
                                    delivery="progressive"
                                    type="video/mp4"
                                    width="640"
                                    height="360"
                                    bitrate="400"
                                    codec="H.264"
                                    scalable="true"
                                    maintainAspectRatio="true"
                            >
                                <![CDATA[https://example.com/video-asset.mp4]]>
                            </MediaFile>
                        </MediaFiles>
                    </Linear>
                </Creative>
            </Creatives>
        </InLine>
    </Ad>
</VAST>