Flipkart Commerce Cloud

Sponsored Product Ads

Getting Started

Sponsored Product Ads are performance ads which help advertisers meet their goals by promoting their individual product listings to the relevant and high intent customers to boost their visibility and increase sales. Network Publishers can offer Sponsored Product Ads to their advertisers by integrating FCC Ads Managers to monetize their properties such as website, msite and Apps (Android & iOS).

Who can integrate with FCC for Sponsored Product Ads?

  1. You’re a Flipkart Commerce Cloud Customer.
  2. You have subscription or trail access to FCC Ads Manager.
  3. You own one or more customer properties – website, mobile app (Android / iOS), mSite.
 

How can I integrate with the FCC Ads Manager?

Server-to-Server integration is required with FCC Ads Manager to support Sponsored Product Ads.

Details required to be onboarded on FCC Ads Manager

Network Details

Each network, an aggregation of demand from advertisers and supply from publishers, has to be onboarded on the FCC Ads Manager. 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 Ads Manager. The ad inventory needs to be defined according to the guidelines here.

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 here. If a publisher is an existing customer of FCC Ads Manager and all the information has already been shared with FCC Ads Manager, then this information may not be required.

Supported Ad Formats

Sponsored Product Ads supports Native ads format.

Catalog Details

Network Publishers need to share the catalog information with FCC Ads Manager which will be used to create Sponsored Product Ad campaigns as well as to generate reports. Catalog information required can be found here.

API Integration Guidelines

Introduction

The Sponsored Product Ads Server to Server API spec allows publishers to integrate with FCC Ads Manager 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 Ads Manager.

API Endpoint

Publishers can use the following endpoints to integrate with the FCC Ads Manager for Sponsored Product Ads:

/v1/spa/getBids?client=

Header Params

Param Description Values
Content-Type The MIME type of the body of the request application/json
X-PERF-TEST send true if testing, Default false  
X-Auth-Token Token to validate clients, Will be shared post contracts are finalised  

 

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

 

AdRequest

Attributes Type Required/Optional Default Description
id String Required   Unique id of the request for each advertisement batch request from the external publisher
type String Required   The request type. Currently only “SEARCH” is supported.
user User Recommended   Human user of the device; audience for advertising
device Device Required   Device object containing the details of the user’s device to which the impression needs to be delivered.
test Integer Required   Toggle indicating bill-ability of the bid
app/site App/Site Required   Details of the application calling for the impression. Only one object to be passed in an Ad request (either app object or site object)
query String Required   The search query
query_lang String Optional ‘en’ The language of the search query. Supported Values – ‘en’
query_ String Optional None The original query request was made by the user, in case the query was augmented.
filters Array of Filter Optional  

The set of product filters to apply to this search. A single filter can specify one or more matching criteria. If a single filter is provided, products that match at least one of these criteria will be returned. If more than one filter is provided, then only products that match at least one criteria in each filter will be returned.

OR relationship among values of same filter

AND relationship among filters

ordering String Optional ‘RELEVANCE’ The search result ordering. Supported Values – ‘RELEVANCE’.
placement_requests Array of PlacementRequest Required   The ad requests by placement

 

User

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 Default Description
id String Recommended   Publisher specific ID for the user. 

 

Device

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 Default Description
ua String Recommended   User Agent of the device. This must be the original user agent without any modifications.
dnt Integer Optional   Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track.
lmt Integer Optional   “Limit Ad Tracking” signals commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.
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 dev
osv String Recommended   Version of the Operating System currently installed on the device.
ifa String Recommended  

Unique AdId for the device, called Identifier for Advertising (IDFA) for iOS devices & 

Google Advertising ID (AAID) for Android. Use visitorId as proxy for msite & website or if ifa is not available

 

App

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 Default Description
id String Required   Unique publisherName registered with FCC
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

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 Default Description
id String Required   Unique publisherName registered with FCC
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”)

 

Filter

Attributes Type Required/Optional Default Description
field String Required   The name of the field to which this filter applies
value Array of String Required   The set of values on which to apply the matching operation
type String Required   The type of matching to perform, acceptable values are [eq, range, ge, le]

 

PlacementRequest

Attributes Type Required/Optional Default Description
placement String Required   The placement type. Supported Values – SEARCH
count Integer Required   The number of ads requested, should be generally more than desired, considering publisher side filtering
offset Integer Optional 1 When requesting more ads for a query by a user, set this to the value of the offset of the last ad that was displayed. Used when user pages through search results and search ads in previous response have been exhausted, or if search ads in previous response are ineligible for display for some reason such as duplicates in the organic search.

 

Ad Request Sample

				
					{
  "id": "a7sIT12513",
  "type": "SEARCH",
  "query": "Bluetooth speakers",
  "query_lang": "en",
  "query_": "Bluetooth speakers",
  "app": {
    "id": "3PHOTMN56F",
    "name": "noon",
    "domain": "noon.com"
  },
  "device": {
    "dnt": 0,
    "ua": "Dalvik/2.1.0 (Linux; U; Android 7.0; SM-J701F Build/NRD90M)",
    "ip": "127.0.0.1",
    "lmt": 0,
    "os": "Android",
    "osv": "7.0",
    "ifa": "4848c544-0ae2-4945-bf67-2ac2293daebb"
  },
  "test": 0,
  "placement_requests": [
    {
      "placement": "SEARCH",
      "count": 1,
      "offset": 10
    }
  ],
  "filters": [
    {
      "value": [
        "6",
        "7",
        "8"
      ],
      "field": "Size",
      "type": "eq"
    }
  ],
  "user": {
    "id": "C785902B8150944B"
  }
}
				
			

Response Object

Top level ad response object contains JSON for payload with the response containing ad products and tracking event details.

AttributesTypeRequired/OptionalDefaultDescription
idStringRequired Unique id of this ad response
placement_responses

Array of 

PlacementResponse

Required Array of placementResponse that contain ads by placementRequest

PlacementResponse

AttributesTypeRequired/OptionalDefaultDescription
placementStringRequired The requested placement. Supported Values – SEARCH
adsArray of AdRequired The list of ads, In case no matching ads could be found, an empty array will be returned.

 

Ad

AttributesTypeRequired/OptionalDefaultDescription
positionIntegerRequired The relative position of the ad in the response. This position should be respected while displaying ads, as earlier positions indicate more relevant ads
skuStringRequired The sku id of the product ad
product_idStringRequired The product id of the product ad.
trackingTrackingRequired The FCC Ad Manager tracking urls for this ad.

 

Tracking

AttributesTypeRequired/OptionalDefaultDescription
impression_urlStringRequired url to be called on ad impression
view_urlStringRequired url to be called on ad view
click_urlStringRequired url to be called on ad click

 

Ad Response Sample

				
					{
  "id": "a7sIT12513",
  "placement_responses": {
    "placement": "SEARCH",
    "ads": [
      {
        "position": 1,
        "sku": "skuId24135",
        "product_id": "productId#865423",
        "tracking": {
          "impression_url": "https://abc.com/v1/spa/tr/impression?pl=R165XpGbjmmc2odsPUYrct0qeeCe034ovi3a2LV4ygAYzjaaaktqmgNjqTXlg_564AtL6L1s-12XVF1le6J9plDCVWrCIW9dY9ZkroAEjKP0sB0bqxx56G-toSKXTSxaHeKzECKOA4cOrUg5MRcsR_rPOPlMiWtQmlflkyegm5GcDuwEZ2b6_AtmQcfGCwe0yWuCLAA-cclCmOFu4nlpltRCVIEcei4qjbAwodH4XJc",
          "view_url": "https:/abc.com/v1/spa/tr/view?pl=R165XpGbjmmc2odsPUYrct0qeeCe034ovi3a2LV4ygAYzjaaaktqmgNjqTXlg_564AtL6L1s-12XVF1le6J9plDCVWrCIW9dY9ZkroAEjKP0sB0bqxx56G-toSKXTSxaHeKzECKOA4cOrUg5MRcsR_rPOPlMiWtQmlflkyegm5GcDuwEZ2b6_AtmQcfGCwe0yWuCLAA-cclCmOFu4nlpltRCVIEcei4qjbAwodH4XJc&vst=[STARTTIME]&vet=[ENDTIME]",
          "click_url": "https://abc.com/v1/spa/tr/click?pl=R165XpGbjmmc2odsPUYrct0qeeCe034ovi3a2LV4ygAYzjaaaktqmgNjqTXlg_564AtL6L1s-12XVF1le6J9plDCVWrCIW9dY9ZkroAEjKP0sB0bqxx56G-toSKXTSxaHeKzECKOA4cOrUg5MRcsR_rPOPlMiWtQmlflkyegm5GcDuwEZ2b6_AtmQcfGCwe0yWuCLAA-cclCmOFu4nlpltRCVIEcei4qjbAwodH4XJc&cet=[EVENTTIME]"
        }
      }
    ]
  }
}
				
			

Recording Events on the Ads

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

  1. Impression: This event has to be fired when the ad is loaded on the client (app/site).
  2. 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.)
  3. 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:

  1. Get the list of URLs for that event for the ad from the ad markup.
  2. 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 capping system can work.

 

Impression Tracker

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

Type: GET

Sample: https://host:port/v1/spa/tr/impression?pl=encryptedPayload

Query ParamsDescription
plThis 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/v1/spa/tr/view?pl=encryptedPayload&vst=[STARTTIME]&vet=[ENDTIME]

Query ParamsDescription
plThis will contain the encrypted data generated while serving.
vstThis is the start time of the view event i.e the instance when the banner comes into the view port for the first time.
vetThis 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&cet=[CLICKSTARTTIME]

Query ParamsDescription
plThis will contain the encrypted data generated while serving.
cetThis is the event time i.e when the click event is triggered.

 

Catalog Information

Product (Entity)

AttributesTypeRequired/OptionalDefaultDescription
idStringRequired Unique id of the product within a catalog
productAttributesProductAttributesOptional contains all product fields, Required for registering or Updating a product, Optional if only updating sku details
skusSKU ArrayRequired list of sku details

 

ProductAttributes

AttributesTypeRequired/OptionalDefaultDescription
titleStringRequired Title of the product
descriptionStringRequired Description of the product
isActiveBooleanRequiredtrueTo mark a product active or inActive, send false to soft delete a product
eventTimeLongRequired Timestamp of event generation time in milliseconds, in case of duplicates latest would apply
linkStringRecommended URL directly linking to your item’s page on your website
mobileLinkStringRecommended Link to a mobile optimized version of the landing page
imageLinkStringRequired URL of an image of the item, required for SPA
additionalImageLinksString ArrayOptional Additional Image URLs
brandStringRequired BrandId of the product like 54325 or PumaOriginal (if names are used as id)
categoryStringRequired Full category path in category Ids like 123/542/567 or Mobile/Handsets/IPhoneGold (if names are used as id)
itemGroupIdStringOptional If this product is part of a group of products & there is a unique itemGorupId maintained, should be same for all products in a group
priceDoubleOptional if there a price associated with product itself
colorStringOptional Color of the product
materialStringOptional Material of the product
modelStringOptional Model number of the product
mpnStringOptional Manufacturer Product Number 
upcStringOptional Globally recognised universal ids for the product
sizeStringOptional Size of the item
conditionStringOptional Condition of the product like – New, Refurbished
ageGroupStringOptional ageGroup product is suitable for like – kids, adult
genderStringOptional Gender for which the product is meant for like men, women, unisex
gtinStringOptional Global Trade Item Number (GTIN)
additionalAttributesAttribute ArrayOptional Optional additional Attributes

 

Attribute

AttributesTypeRequired/OptionalDefaultDescription
nameStringRequired Name of the attribute
valueStringRequired Value of the attribute

 

SKU

AttributesTypeRequired/OptionalDefaultDescription
idStringRequired Unique sku id within a catalog, should be unique across products
sellerIdStringRequired Unique id of the seller to which the sku belongs to, unique within the catalog
isActiveBooleanRequiredtrueTo mark a sku active or inactive, send false to soft delete a sku
priceDoubleRequired Current sku price, in catalog currency
availabilityStringOptional can send values from ENUM list [AVAILABLE, OUT_OF_STOCK, COMING_SOON]
inventoryIntegerOptional Number of units available

 

Seller (Entity)

AttributesTypeRequired/OptionalDefaultDescription
idStringRequired Unique sellerId within a catalog
nameStringRequired Display name for the seller
isActiveBooleanRequiredtrueTo mark a seller active or inActive, send false to soft delete a seller

 

Brand List

Sample Json format

				
					{
  "brands": [
    {
      "id": "123",
      "name": "Puma"
    },
    {
      "id": "124",
      "name": "Nike"
    },
    {
      "id": "125",
      "name": "Adidas"
    }
  ]
}
				
			

Category Tree

Sample Json format
				
					{
  "categories": [
    {
      "id": "123",
      "name": "Mobile",
      "categories": [
        {
          "id": "1231",
          "name": "Nokia",
          "categories": []
        }
      ]
    },
    {
      "id": "124",
      "name": "Home",
      "categories": [
        {
          "id": "1241",
          "name": "Appliances",
          "categories": []
        },
        {
          "id": "1242",
          "name": "Decor",
          "categories": []
        }
      ]
    }
  ]
}
				
			
Important Note for Brand and Category Schema
  1. Partial updates are not supported. If there is any change, the full updated data needs to be shared.
  2. It should be 1 line of valid json.
  3. Ids should be unique within 1 json shared.

Advertiser Account Onboarding

Details required for Onboarding an advertiser account:

  1. Advertiser / Brand Account Name
  2. Email Address
  3. Company Phone Number
  4. Company website URL
  5. Communication address
  6. Top-level domain
  7. Billing Name
  8. VAT Registration Number (or any other document equivalent for that country)
  9. Billing Address
  10. Service Tax Number equivalent for that country

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 monetizable ad inventory to the advertisers.

Get the case study

We would need your email to share this case study.