Sponsored Product Ads – FCC Ads Manager

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 the FCC for Sponsored Product Ads?

You’re a Flipkart Commerce Cloud Customer.
You have subscription or trial access to FCC Ads Manager.
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=<client_id>

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.
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.
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	0	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"
  },
 
  "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.

Attributes

Type

Required/Optional

Default

Description

String

Required

Unique id of this ad response

placement_responses

Array of

PlacementResponse

Required

Array of placementResponse that contain ads by placementRequest

PlacementResponse

Attributes	Type	Required/Optional	Default	Description
placement	String	Required		The requested placement. Supported Values – SEARCH
ads	Array of Ad	Required		The list of ads, In case no matching ads could be found, an empty array will be returned.

Attributes	Type	Required/Optional	Default	Description
position	Integer	Required		The relative position of the ad in the response. This position should be respected while displaying ads, as earlier positions indicate more relevant ads
sku	String	Required		The sku id of the product ad
product_id	String	Required		The product id of the product ad.
tracking	Tracking	Required		The FCC Ad Manager tracking urls for this ad.

Tracking

Attributes	Type	Required/Optional	Default	Description
impression_url	String	Required		url to be called on ad impression
view_url	String	Required		url to be called on ad view
click_url	String	Required		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:

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 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 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/v1/spa/tr/view?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&cet=[CLICKSTARTTIME]

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

Catalog Information

Product (Entity)

Attributes	Type	Required/Optional	Default	Description
id	String	Required		Unique id of the product within a catalog
productAttributes	ProductAttributes	Optional		contains all product fields, Required for registering or Updating a product, Optional if only updating sku details
skus	SKU Array	Required		list of sku details

ProductAttributes

Attributes	Type	Required/Optional	Default	Description
title	String	Required		Title of the product
description	String	Required		Description of the product
isActive	Boolean	Required	true	To mark a product active or inActive, send false to soft delete a product
eventTime	Long	Required		Timestamp of event generation time in milliseconds, in case of duplicates latest would apply
link	String	Recommended		URL directly linking to your item’s page on your website
mobileLink	String	Recommended		Link to a mobile optimized version of the landing page
imageLink	String	Required		URL of an image of the item, required for SPA
additionalImageLinks	String Array	Optional		Additional Image URLs
brand	String	Required		BrandId of the product like 54325 or PumaOriginal (if names are used as id)
category	String	Required		Full category path in category Ids like 123/542/567 or Mobile/Handsets/IPhoneGold (if names are used as id)
itemGroupId	String	Optional		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
price	Double	Optional		if there a price associated with product itself
color	String	Optional		Color of the product
material	String	Optional		Material of the product
model	String	Optional		Model number of the product
mpn	String	Optional		Manufacturer Product Number
upc	String	Optional		Globally recognised universal ids for the product
size	String	Optional		Size of the item
condition	String	Optional		Condition of the product like – New, Refurbished
ageGroup	String	Optional		ageGroup product is suitable for like – kids, adult
gender	String	Optional		Gender for which the product is meant for like men, women, unisex
gtin	String	Optional		Global Trade Item Number (GTIN)
additionalAttributes	Attribute Array	Optional		Optional additional Attributes

Attribute

Attributes	Type	Required/Optional	Default	Description
name	String	Required		Name of the attribute
value	String	Required		Value of the attribute

SKU

Attributes	Type	Required/Optional	Default	Description
id	String	Required		Unique sku id within a catalog, should be unique across products
sellerId	String	Required		Unique id of the seller to which the sku belongs to, unique within the catalog
isActive	Boolean	Required	true	To mark a sku active or inactive, send false to soft delete a sku
price	Double	Required		Current sku price, in catalog currency
availability	String	Optional		can send values from ENUM list [AVAILABLE, OUT_OF_STOCK, COMING_SOON]
inventory	Integer	Optional		Number of units available

Seller (Entity)

Attributes	Type	Required/Optional	Default	Description
id	String	Required		Unique sellerId within a catalog
name	String	Required		Display name for the seller
isActive	Boolean	Required	true	To mark a seller active or inActive, send false to soft delete a seller

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

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.

				
					{
  "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

Partial updates are not supported. If there is any change, the full updated data needs to be shared.
It should be 1 line of valid json.
Ids should be unique within 1 json shared.

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

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.

Sponsored Product Ads – FCC Ads Manager

Getting Started

Who can integrate with the FCC for Sponsored Product Ads?

How can I integrate with the FCC Ads Manager?

Details required to be onboarded on FCC Ads Manager

Network Details

Inventory Details

Advertiser Account Details

Supported Ad Formats

Catalog Details

API Integration Guidelines

Introduction

API Endpoint

Header Params

Request Method

Required HTTP Headers

AdRequest

User

Device

App

Site

Filter

PlacementRequest

Ad Request Sample

Response Object

PlacementResponse

Ad

Tracking

Ad Response Sample

Recording Events on the Ads

Impression Tracker

View Tracker

Click Tracker

Catalog Information

Product (Entity)

ProductAttributes

Attribute

SKU

Seller (Entity)

Advertiser Account Onboarding

Supply Definition Guidelines

Category Tree

Advertiser Account Onboarding

Supply Definition Guidelines

RetailIntelligenceat Scale

Get the case study

Retail
Intelligence
at Scale