Getting Started

Sponsored Product Ads are performance ads that 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?

  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=<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.

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 Sampl

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

 

Attributes

Type

Required/Optional

Default

Description

id

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.

 

Ad

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-toSK
         XTSxaHeKzECKOA4cOrUg5MRcsR_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 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:

  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.