Getting Started

Flipkart Commerce Cloud’s Ad monetisation service (FCC AdMon Service) enables you to monetise your properties such as website, MSite, and Apps (Android and iOS) by selling ad spaces. Presently, the supported advertising content includes ‘Display ads’ on your properties (websites, mobile apps) across geographies and across publishers.

Who can integrate with Ad-Tech Services?

You’re a Flipkart Commerce Cloud Customer
You have subscription or trial access to FCC Ad Monetization product
You own one or more consumer properties – website, mobile app (Android/iOS), mSite

How can I integrate with FCC AdMon Service?

OpenRTB is the main integration process for working with the FCC AdMon Service.

Details required to be onboarded on FCC AdMon Service

Network Details

Each network, an aggregation of demand from advertisers and supply from publishers, has to be onboarded on the FCC AdMon Service. The details required for network onboarding have to be shared offline.

Inventory Details

The monetizable ad inventory available on the web/app has to be onboarded as supply constructs on the FCC AdMon Service. The ad inventory needs to be defined according to the guidelines mentioned in this document.

Creative format Specifications

Specifications for the creative formats that need to be supported and integrated into the FCC AdMon service have to be shared offline. These include:

Channels supported for given Creative Format (Desktop, Msite, IOS, Android, Tablet)
Image Dimensions supported for given Creative Format ( Height and Width of the image)

Advertiser Account Details

For an advertiser who wants to advertise on the Publisher, there will be an advertiser account, the details can be shared offline and the account admin will onboard the account. The details required for the advertiser account onboarding can be found in this document itself.

Key-Value Pair User Segments for Targeting (Optional)

Key-value pair targeting will be provided as a feature to the publishers to define custom targeting criteria such as demographics, behaviour etc. When an Ad request will come from a publisher that has key-values in the request, demand that targets those key-values will be eligible to serve for that Ad request.

Defining Key-Value pairs

Pre-defined list of key-values has to be shared by the publisher for segment definition and to be used for targeting in demand creation in ad serving. All the possible values for a particular key will have to be shared by the publisher. For example:

Age
- 18-32
- 33-60
Gender
- Male
- Female
- Unknown

The publisher will pass the same “key-value” pair in the ad request against which the applicable campaigns based on the targeting criteria will be selected.

CDN Details

Each network, an aggregation of demand from advertisers and supply from publishers, will provide access to their CDN to upload the creatives so that Ads can be served efficiently.

Fallback Banner

Each publisher needs to have a fallback mechanism where if an Ad banner is not served due to any reason, then a default banner can be shown for that slot. The dimensions of the fallback banner should be defined as per the dimensions of the slot.

Getting Started with OpenRTB

FCC Ad Monetisation service supports the integration specifications for OpenRTB 2.5. We have also provided example requests and responses to make it easier for you to understand the integration process.

Introduction to OpenRTB

OpenRTB project provides open industry standards for communication between buyers of advertising and sellers of publisher inventory. The overall goal of OpenRTB is and has been to create a lingua franca for communicating between buyers and sellers.

The following figure illustrates the OpenRTB interactions between an exchange and its bidders. Ad requests originate at publisher sites or applications. For each inbound ad request, bid requests are broadcast to bidders, responses are evaluated under prevailing auction rules, and a winner is selected. The winning bidder is notified of the auction win via a win notice. Ad markup can either be included in the bid prospectively or in response to the win notice.

A separate billing notice is also available to accommodate varying policies enacted by exchanges that are beyond the scope of the OpenRTB specification (e.g., billing on device delivery, viewability, etc.). The win notice informs the bidder’s pricing algorithms of a success, whereas the billing notice indicates that spend should actually be applied. A loss notification is also available to inform the bidder of the reason their bid did not win.

The URLs for win, billing, and loss notices and the ad markup itself can contain any of several standard macros that enable the exchange to communicate critical data to the bidder (e.g., clearing price).

For the purpose of integration with the FCC AdMon Service, only Bid Request and Bid Response are relevant.

Supported Ad Formats

FCC AdMon Service supports Native display ads format.

API Integration Guidelines

Introduction

The FCC AdMon Server to Server API spec allows publishers to integrate with FCC AdMon Service directly from their server. This document lays out the Ad request, response structures and the parameters included in each of them to enable publishers to integrate with FCC AdMon Service .

API Endpoint

Publishers can use the following endpoints to integrate with the FCC AdMon Service:

v1/dsp/getBids?client=publisherId

HEADER PARAM:

X-AUTH-TOKEN: This is the unique Authentication Key generated on FCC’s end and shared with the client. Inorder to get the response successfully, passing this header in the request will be crucial

X-PERF-TEST: true, for non-production & performance testing flows and false, for production flows

Publisher ID will be shared after the network is onboarded

Request Method

Ad requests must be sent using the HTTPS Post method. All request parameters must be sent within a JSON object within the POST body.

Required HTTP Headers

Header Name	Description	Values
Content-Type	The MIME type of the body of the request	application/json

Request Object

The top-level ad request object contains the entire JSON payload with the request. The child objects and parameters under the Request object are described in the following table:

Object/Parameter	Type	Required / Optional	Description
id	String	Required	Unique id of the bid request for each advertisement batch request from the external publisher.
imp	Object Array	Required	Array of imp objects representing the supply metadata for each monetizable impression entity . At least one impression object is required.
device	Object	Required	Device object containing the details of the user’s device to which the impression needs to be delivered.
app / site	Object Array	Optional	Details of the application calling for the impression. Only one object to be passed in an Ad request (either app object or site object).
wlang	String Array	Optional (english = “en”)	White list of languages for creatives using ISO-639-1-alpha-2.
user	Object	Conditionally Mandatory	Human user of the device; audience for advertising.

Imp Object

The imp object defines the type and number of ad impressions desired by the publisher. A single bid request can include multiple imp objects with unique ID values so the bids can reference them individually.

This is a mandatory object in the ad request and must contain the parameters described in the table below.

Attributes	Type	Required / Optional	Description
id	String	Required	A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).
banner	Object	Required	To denote the banner dimensions.
ext	Object	Required	Extension to the impression object for sending supply metadata in context of the impression.

Imp.banner.format Object

This object represents an allowed size (i.e. width and height combination) or Flex Ad parameters for a banner impression. These are typically used in an array where multiple sizes are permitted.

Attributes	Type	Requires / Optional	Description
w	Integer	Required	Width in device independent pixels (DIPS).
h	Integer	Required	Height in device independent pixels (DIPS).

Imp.ext Object

This object denotes extension to the impression object for sending supply metadata in context of the impression.

Attributes	Type	Requires / Optional	Description
slotId	String	Required	A unique identifier for the slot in the ad space within the context of the impression.

Device Object

This object provides information pertaining to the device through which the user is interacting. Device information includes its hardware, platform, location, and carrier data.

Attributes	Type	Required / Optional	Description
ua	String	Recommended	User Agent of the device. This must be the original user agent without any modifications.
ip	String	Recommended	IP Address of the device in IPv4 format. Required if the ipv6 field is absent.
os	String	Recommended	Name of the Operating System currently installed on the device.
osv	String	Recommended	Version of the Operating System currently installed on the device.
ifa	String	Conditionally Mandatory	Identifiers for Advertisers on the iOS platform. Mandatory if the app object is present in the request. If app object is present but request does not contain ifa (for iOS only) the request will be invalidated.

App Object

This object should be included if the ad supported content is a non-browser application (typically in mobile) as opposed to a website. A bid request must not contain both an App and a Site object.

Attributes	Type	Required / Optional	Description
id	String	Recommended	publisher specific app ID.
name	String	Optional	App name (may be aliased at the publisher’s request).
domain	String	Optional	Domain of the app (e.g., “mygame.foo.com”)

Site Object

This object should be included if the ad supported content is a website as opposed to a non-browser application. A bid request must not contain both a Site and an App object.

Attributes	Type	Required / Optional	Description
id	String	Recommended	publisher specific site ID.
name	String	Optional	site name (may be aliased at the publisher’s request).
domain	String	Optional	Domain of the site (e.g., “mygame.foo.com”)

User Object

This object contains information known or derived about the human user of the device (i.e., the audience for advertising). The user id is an exchange artifact and may be subject to rotation or other privacy policies. However, this user ID must be stable long enough to serve reasonably as the basis for frequency capping and retargeting.

Attributes	Type	Required / Optional	Description
id	String	Recommended	Publisher specific ID for the user. At least one of id is recommended.
data	Object Array	Optional	Additional user data. Each data object represents a different data source.

User.data Object

The data and segment objects together allow publishers to define custom targeting criteria such as demographics, behaviour etc. to target different set of audience. When an Ad request will come from a publisher that has key-values in the request, demand that targets those key-values will be eligible to serve for that ad request.

Attributes	Type	Required / Optional	Description
name	String	Conditionally Mandatory	Pass user_targeting in this field for custom targeting.
segment	Object Array	Conditionally Mandatory	Array of Segment objects that contain the actual data values.

User.data.segment Object

Segment objects are essentially key-value pairs that convey specific units of data. The parent Data object is a collection of such values from a given data provider. The specific segment names and value options must be published by the publisher a priori to its FCC AdMon service.

Attributes	Type	Required / Optional	Description
name	String	Conditionally Mandatory	Name of the data segment specific to the FCC AdMon service.
value	string	Conditionally Mandatory	String representation of the data segment value.

Limits on Name-Value Pair in Segment Object

Limits defined below are for active names and values, any name or value deleted by the user will not be counted to calculate the system limit.

Parameter	Limit
Maximum number of active names supported per publisher	100
Maximum number of active values per key	100,000
Characters per name	30
Characters per value	50

Following characters will not be allowed in key names or values:
- , (comma)

Ad Request Sample

Native Ads

Response Object

Top level ad response object contains JSON for payload with the response. A bid response may contain bids from one or more seats (entities representing the advertisers or brands). The bid response consists of a Bid Response id and a Seatbid object as mandatory attributes.

Attribute	Type	Required / Optional	Description
id	string	Required	Id of the bid request to which this is a response. This is a reflection of the bid request ID for logging purposes.
seatbid	Object array	Required	Array of seatbid objects with a minimum of one seatbid object.

Seatbid (seatbid)

A bid response can contain multiple Seatbid objects, each on behalf of a different bidder seat and each containing one or more individual bids.

Attributes	Type	Required / Optional	Description
bid	Object array	Required	Array of Bid objects each related to an impression. Multiple bids can relate to the same impression.

Bid (bid )

A SeatBid object contains one or more Bid objects, each of which identified by an id, relates to a specific impression in the bid request via the impid attribute and constitutes an offer to buy that impression.

Attributes	Type	Required / Optional	Description
id	String	Required	Bidder generated bid ID to assist with logging/tracking. It will be generated on the FCC end. Client need not understand it.
impId	String	Required	ID of the Imp object in the related bid request.
adm	String	Required	Ad markup containing the ad that will be rendered on the publisher property and meta information of the creative.
nurl	String	Optional	Win notice URL called by the exchange if the bid wins (not necessarily indicative of a delivered, viewed, or billable ad); optional means of serving ad markup.
lurl	String	Optional	Loss notice URL called by the exchange when a bid is known to have been lost.
cid	String	Required	Campaign ID for the given creative
price	Float	Optional	It is only useful for bidding scenarios. For FCC integration, this field will be 0.0, because we are assuming 100% Bid win
ext	Object	Required	Placeholder for bidder-specific extensions to OpenRTB

bid.adm (Ad markup)

FCC AdMon Service passes the ad markup as part of the bid response. JSON is used to pass the ad markup. Following are the attributes that are passed as part of adm:

Attributes	Type	Required / Optional	Description
version	String	Optional	Version of the native template
assets	Object Array	Required	List of assets to be rendered by the client
impUrls	String Array	Required	List of impression URLs to be fired by the client. Details [here](#recording-events-on-the-ads).
viewUrls	String Array	Required	List of view URLs to be fired by the client. Details [here](#recording-events-on-the-ads)
clickUrls	String Array	Required	List of click URLs to be fired by the client. Details [here](#recording-events-on-the-ads)

bid.ext (Bid Extension)

FCC AdMon Service passes the Bid Extension in order to send FCC customized response objects. Following are the attributes that are passed as part of adm:

Attributes	Type	Required / Optional	Description
slot_id	String	Required	Slot ID for which this Bid is being Served. This can be used in the demand & supply matching when are the multiple impressions requested which will lead to multiple Bids in the response object
ad_group_id	String	Required	AD group ID for the provided Banner
rich_media_payload	Object	Optional	If the creative is a Rich Banner, additional attributes will be part of this Object

bid.ext.rich_media_payload (Rich Banner Attributes)

FCC AdMon Service passes the Rich Banner Attributes in order to support client with Rich Banner. It will contain all the attributes of Rich Banner which are configured in the AD while AD creation FCC customized response objects. All the below fields will be conditionally present i.e. If the Advertiser has configured the field it will be present in the response, else it won’t be present. Following are the attributes that are passed as part of adm:

Attributes	Type	Required / Optional	Description
ad_title	String	Optional	Contains Ad Title as per Rich Media requirements
ad_subtitle	String	Optional	Contains Ad Subtitles
ad_description	String	Optional	Contains Ad Description
cta_text	String	Optional	Contains CTA Text
cta_bg_color	String	Optional	Contains Hexadecimal Code for CTA Background Color
ad_logo_image	String	Optional	Contains Logo Image URL [Dimensions won’t be modified by FCC, It will be equal to the image uploaded]
image_bg_color	String	Optional	Contains Hexadecimal Code of Image Background color

adm.assets Object

Attributes	Type	Description
id	Integer	Unique Id of the asset
img	Object	Image Object
native	Object	Native Data

assets.img Object

Attributes	Type	Description
url	String	Image Url
width	int	Height of the Image
height	int	Width of the Image

assets.native Object

Attributes	Type	Description
value	String	Custom asset value
type	String	Type of the custom asset. Example : LP (Landing Page) and the value across this object will be Landing Page url for given Banner

Ad Response Sample

Native Ads

				
					{

 "id": "DCADJHFABHB12447VNAJDN",

 "imp": [

   {

     "id": "DFGB3567DVBNSJ5FBN6",

     "banner": {

       "format": [ {"h": 12, "w": 12}, {"h": 12, "w": 12}]

     },

     "ext": {

       "slotid": "HOME-PAGE-DAILY"

     }

   }

 ],

// only one object to be passed in an ad request (either site object or app object)

 "app": {
    "id": "1",
    "name": "CompanyName",
    "domain": "companyname.com"
 },
 
  "site": {
  "id": "1",
  "name": "CompanyName",
  "domain": "companyname.com"
 },      

 "device": {

    "ua": "Dalvik/2.1.0 (Linux; U; Android 7.0; SM-J701F Build/NRD90M)",

    "ip": "127.0.0.1",

    "ifa": "kjsdnf",

    "os": "Android",

    "osv": "7.0"
 },

"user": {

    "id": "C785902B8150944B",

    "data": [ {

        "name": "user_targeting", // This should be exact Match

        "segment": [ {

            "name": "key1",

            "value": "value1,value2"

        },
        {

            "name": "key2",

            "value": "10-20,30-40,50-60"

        }]

    }]

},
 "wlang": ["en"],
 "content": {
    "keywords": "keyword-a"
    }


}

				
					{

   "id": "DCADJHFABHB12447VNAJDN",

   "seatbid": [

       {

           "bid": [

               {

                   "id": "AL2PPRCAAAAAGIAAB_1_DF456GF5GD",

                   "impid": "SDFGHJ356AGDBN3",

                   "price": 0.0,

                   "nurl": "http://abc.com/bidWin?pl=sgZUyf1P5jiFimOVV0hqmcm0sljwUuJBPIRFpFyVIqShpstMGcpzV4LIEKOjY72bSQOTwRwZ0EbrZRJX73x7LVznhj0cknhVjvpwHDfXfoI1tNxgzpIau4b5xJfyqoCfcyQaKfCcLZ6koVEQLE2I3T7_0At4SQWiGybANN7e1L_X9lXc2D7s3MvYT9N85-hv&p=${AUCTION_PRICE}&cur=${AUCTION_CURRENCY}",

                   "lurl": "http://abc.com/bidLoss?pl=sgZUyf1P5jiFimOVV0hqmcm0sljwUuJBPIRFpFyVIqShpstMGcpzV4LIEKOjY72bSQOTwRwZ0EbrZRJX73x7LVznhj0cknhVjvpwHDfXfoI1tNxgzpIau4b5xJfyqoCfcyQaKfCcLZ6koVEQLE2I3T7_0At4SQWiGybANN7e1L_X9lXc2D7s3MvYT9N85-hv&p=${AUCTION_PRICE}&cur=${AUCTION_CURRENCY}&l=${AUCTION_LOSS}",

                   "adm": "{\"version\":\"1.0\",\"assets\":[{\"id\":-1156179165,\"img\":{\"type\":0,\"url\":\"http://abc.com/flap-image/96d2660f51d748bf.jpg\",\"width\":640,\"height\":1440},"native":{"value":"http://xyz.com","type":"LP"}}}],\"impUrls\":[\"http://abc.com/adImpression?pl=sgZUyf1P5jiFimOVV0hqmcm0sljwUuJBPIRFpFyVIqShpstMGcpzV4LIEKOjY72bSQOTwRwZ0EbrZRJX73x7LQQcvgV5TfCGeFgFSBdkLCMLTjiMQs3Lo4cVyS6vkrfGREzz3n6yrmAFwhbb68CQsnOsyYfdTe6WcjFJxqJUh08\"],\"viewUrls\":[\"http://abc.com/adView?pl=sgZUyf1P5jiFimOVV0hqmcm0sljwUuJBPIRFpFyVIqShpstMGcpzV4LIEKOjY72bSQOTwRwZ0EbrZRJX73x7LQQcvgV5TfCGeFgFSBdkLCMLTjiMQs3Lo4cVyS6vkrfGREzz3n6yrmAFwhbb68CQsnOsyYfdTe6WcjFJxqJUh08&vst=[STARTTIME]&vet=[ENDTIME]\"],\"clickUrls\":[\"http://abc.com/adClick?pl=sgZUyf1P5jiFimOVV0hqmcm0sljwUuJBPIRFpFyVIqShpstMGcpzV4LIEKOjY72bSQOTwRwZ0EbrZRJX73x7LQQcvgV5TfCGeFgFSBdkLCMLTjiMQs3Lo4cVyS6vkrfGREzz3n6yrmAFwhbb68CQsnOsyYfdTe6WcjFJxqJUh08&cet=[EVENTTIME]\"]}",

                   "adomain": [

                       "www.flipkart.com"

                   ],

                   "cat": [

                       "IAB19-2"

                   ],

                   "exp": 3600,
         
                   "cid": "7NPOTBTCO6YU",

                   "ext": {

                       "creative_duration": 0,

"slot_id": "WCALHB0VR6IDE",
            
"ad_group_id": "14ASD523DV0A",
            
"rich_media_payload": {

              "ad_title": "Rich Media Title",

              "ad_subtitle": "Rich Media Subtitle",

              "ad_description": "Rich Media Description",

              "cta_text": "Click Here for details",

              "cta_bg_color": "#5499C7",

              "ad_logo_image": "https://fcc.flipkart.com/imageurl.png",

              "image_bg_color": "#17202A"
          		  }

                   }

               }

           ]

       }

   ],

   "bidid": "AL2PPRCAAAAAGIAAB",

   "cur": "INR"

}

Recording events on the Ads

The FCC AdMon service tracks the ad interaction events only when the trackers are fired. The events that are tracked are:

Impression: This event has to be fired when the ad is loaded on the client (app/site)
View: This event has to be fired when the ad is in the viewable port for the user. Viewability can be defined by the publisher. (Recommended: IAB guidelines – ad which appears at least 50% on screen for more than one second.)
Click: This event has to be fired when the user clicks on the advertisement.

To record impression/ view /click on the ad, follow these steps:

Get the list of URLs for that event for the ad from the ad markup.
For each tracker url, do the following:
1. Send a GET request to the urls, with an http client.
2. Retry up to 5 times if the url fails, with an exponential backoff defined by retryTime * Uniform[0, 1], and retryTime doubled for every failure with start retry time as 1 second.

The tracker events have to be fired in real time so that the budget and frequency capping systems can work.

Impression Tracker

This event is to be fired when the tenant ( website / Mobile App SDK receives the Ad Bid response). This event helps in calculating the efficiency of serving Ads.

Type: GET

Sample: https://host:port/adImpression?pl=encryptedPayload

Query Params	Description
pl	This will contain the encrypted data generated while serving.

View Tracker

This event is to be fired when the Ads become visible on the viewport of the user. This event helps in calculating the performance of serving Ads.

Type: GET

Sample: https://host:port/adView?pl=encryptedPayload&vst=[STARTTIME]&vet=[ENDTIME]

Query Params	Description
pl	This will contain the encrypted data generated while serving.
vst	This is the start time of the view event i.e the instance when the banner comes into the view port for the first time.
vet	This is the end time of the view event i.e the instance when the banner comes out of the view port.

Click Tracker

This event is to be fired when the Ads are clicked by the user. This event helps in calculating the performance of serving Ads.

Type: GET

Sample: https://host:port/adClick?pl=encryptedPayload&et=[EVENTTIME]

Query Params	Description
pl	This will contain the encrypted data generated while serving.
et	This is the event time i.e when the click event is triggered.

Error Responses

Error Code	Description
204	Validation Errors If Any

Appendix

Supply Definition Guidelines

Supply constructs and Hierarchy:

Entity	Definition
Network	An aggregation of demand from advertisers and supply from publishers.
Publisher Group	A group of publishers.
Publisher	A website/app that provides monetisable ad inventory to the advertisers.
Page	A publisher website/app consists of many web pages linked together. Each is referred to as a page. For example, Home Page, Product Page etc.
Slot	Each page on a website can be divided into monetisable spaces where an ad can load.
Creative Format	A unique collection of asset types that will be required to create an ad. For example, Banner ad (landing page, image), Rich Banner (landing page, image, Logo, CTA text) etc.

Advertiser Account Onboarding

Details required for Onboarding an advertiser account:

Advertiser / Brand Account Name
Email Address
Company Phone Number
Company website URL
Communication address
Top-level domain
Billing Name
VAT Registration Number (or any other document equivalent for that country)
Billing Address
Service Tax Number equivalent for that country
Upload Documents (Agreement/Cancelled cheque etc – these will differ with each country)

Getting Started

Who can integrate with Ad-Tech Services?

How can I integrate with FCC AdMon Service?

Details required to be onboarded on FCC AdMon Service

Network Details

Inventory Details

Creative format Specifications

Advertiser Account Details

Key-Value Pair User Segments for Targeting (Optional)

Defining Key-Value pairs

CDN Details

Fallback Banner

Getting Started with OpenRTB

Introduction to OpenRTB

Supported Ad Formats

API Integration Guidelines

Introduction

API Endpoint

Request Method

Required HTTP Headers

Request Object

Imp Object

Imp.banner.format Object

Imp.ext Object

Device Object

App Object

Site Object

User Object

User.data Object

User.data.segment Object

Limits on Name-Value Pair in Segment Object

Ad Request Sample

Native Ads

Response Object

Seatbid (seatbid)

Bid (bid )

bid.adm (Ad markup)

bid.ext (Bid Extension)

bid.ext.rich_media_payload (Rich Banner Attributes)

adm.assets Object

assets.img Object

assets.native Object

Ad Response Sample

Native Ads

Recording events on the Ads

Impression Tracker

View Tracker

Click Tracker

Error Responses

Appendix

Supply Definition Guidelines

Advertiser Account Onboarding

RetailIntelligenceat Scale

Get the case study

Retail
Intelligence
at Scale