Getting Started with FCC Ads
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 here.
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:
Asset types (Landing Page, Image, Trackers etc.)
Image Dimensions (maximum height and width of the image)
Supported aspect ratio of the image
File type for the image (png/jpg etc)
Max file size for the image etc.
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 account admin will onboard the account. The details required for the advertiser account onboarding can be found here.
Custom User Segments for Targeting
Custom user segments that will be used for targeting demand will be shared offline by the Publisher Network. These user segment files will contain the anonymised user ID which will be passed in the ad request for targeting the user.
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: Will be shared post contracts are finalised
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
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:
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.
Imp.native Object
This object denotes that the impression is offered as a native ad opportunity.
Imp.ext Object
This object denotes extension to the impression object for sending supply metadata in context of the impression.
Device Object
This object provides information pertaining to the device through which the user is interacting.
Ad Request Sample
Native Ads
{
“id”: “a7sIT125”,
“imp”: [
{
“id”: “OSGMz25”,
“native”: {
“ver”:”1.0″
},
“ext”: {
“slotid”: “DEFAULT_SLOT”
}
}
],
“app”: {
},
“device”: {
“dnt”: 0,
“lmt”: 0,
“ua”: “Dalvik/2.1.0 (Linux; U; Android 7.0; SM-J701F Build/NRD90M)”,
“ifa”: “kjsdnf”,
“os”: “Android”,
“osv”: “7.0”
},
“tmax”: 1000,
“test”: 0
}
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.
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.
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.
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:
adm.assets Object
assets.img Object
assets.native Object
Ad Response Sample
Native Ads
{
“id”: “a7sIT125”,
“seatbid”: [
{
“bid”: [
{
“id”: “AL2PPRCAAAAAGIAAB_1_DF456GF5GD”,
“impid”: “OSGMz25”,
“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,
“ext”: {
“creative_duration”: 0,
“include_cta”: false
}
}
]
}
],
“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:
Send a GET request to the urls, with an http client.
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
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]
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]
Error Responses
Appendix
Supply Definition Guidelines
Supply constructs and Hierarchy:
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)
