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?

  1. You’re a Flipkart Commerce Cloud Customer.

  2. You have subscription or trial 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 ofline.

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 ofline 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

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_564AtL 6L1s-12XVF1le6J9plDCVWrCIW9dY9ZkroAEjKP0sB0bqxx56G-

toSKXTSxaHeKzECKOA4cOrUg5MRcsR_rPOPlMiWtQmlflkyegm5GcDuwEZ2b6_AtmQcfGCwe0yWuCLAA- cclCmOFu4nlpltRCVIEcei4qjbAwodH4XJc&vst;=[STARTTIME]&vet;=[ENDTIME]",

"click_url":

"https://abc.com/v1/spa/tr/click?pl=R165XpGbjmmc2odsPUYrct0qeeCe034ovi3a2LV4ygAYzjaaaktqmgNjqTXlg_564At L6L1s-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 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.

{

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