SPAAdRequest

Top-level ad request for sponsored product ads. Denotes the page for which FCC serves ads and carries the user, device, publisher, and placement context needed to rank product ads.

idstringrequired

Unique id of the request for each advertisement request from the external publisher.

Example: adb853c0-6df3-40e2-b243-efb1b56beb41

typestringrequired

The request type. Denotes the page for which FCC serves ads.

Possible values: [SEARCH, BROWSE]

user objectrequired

User details of the device or audience for advertising. Contains information known or derived about the human user of the device.

The user id is an exchange artifact and may be subject to rotation or other privacy policies. Keep the user id stable long enough to serve as the basis for attribution or personalization use cases.

idstringrequired

User identifier for which FCC serves the ad impression.

Example: C785902B8150944B

device objectrequired

Device object containing the details of the user's device to which FCC delivers the impression. Includes hardware, platform, location, and carrier data.

FCC uses this context to target and deliver the ad correctly to the requesting device.

uastringrequired

User agent of the device. Send the original user agent without any modifications.

Example: Dalvik/2.1.0 (Linux; U; Android 7.0; SM-J701F Build/NRD90M)

ipstring

IP address of the device in IPv4 format. Required if you omit the ipv6 field.

osstring

Name of the operating system currently installed on the device.

osvstring

Version of the operating system currently installed on the device.

ifastring

Unique AdId for the device: Identifier for Advertising (IDFA) for iOS, Google Advertising ID (AAID) for Android. Use visitorId as a proxy for msite and website, or when ifa is unavailable.

app object

Details of the application calling for the impression. Include this object if the ad supported content is a non-browser application (typically mobile).

Required if you omit site. A bid request must not contain both an App and a Site object.

idstringrequired

Unique publisherId FCC registers for the client.

Example: BR7NWI24B41Z6L

namestring

App name. FCC may alias this at the publisher's request.

domainstring

Domain of the app (e.g., mygame.foo.com).

site object

Details of the website calling for the impression. Include this object if the ad supported content is a website as opposed to a non-browser application.

Required if you omit app. A bid request must not contain both a Site and an App object.

idstringrequired

Unique publisherName FCC registers.

namestring

Site name. FCC may alias this at the publisher's request.

domainstring

Domain of the site (e.g., mygame.foo.com).

querystring

The user searched query on the SEARCH page. Required when type is SEARCH.

query_langstring

The language of the search query in ISO 639 two-letter codes (e.g., en, ar, es). This is an optional field, language is detected if not present.

filters object[]

The set of product filters to apply to this search. A single filter can specify one or more matching criteria. If you provide a single filter, FCC returns products that match at least one of these criteria. If you provide more than one filter, FCC returns only products that match at least one criteria in each filter.

Values within a single filter have an OR relationship. Multiple filters have an AND relationship. Filterable fields are product-level attributes ingested in the catalog (e.g., brand_id, category_id_path).

Required when type is BROWSE. Must include a filter on category_id_path or category_id.

Array [

fieldstringrequired

The name of the field to which this filter applies. Filterable fields are product-level attributes ingested in the catalog (e.g., brand_id, category_id_path).

Example: brand_id

valuestring[]required

The set of values on which to apply the matching operation. Values within a single filter have an OR relationship.

Example: ["260332020","260332021"]

typestringrequired

The type of matching to perform.

Possible values: [EQ, RANGE, GE, LE]

]

orderingstring

The search result ordering.

Possible values: [RELEVANCE]

Default value: RELEVANCE

placement_requests object[]required

The ad counts requested for each placement of the page.

FCC currently supports only one placement object per request.

Possible values: >= 1

Array [

placementstringrequired

The placement id. FCC supports onboarded placements for each publisher (e.g., TOP_OF_SEARCH, REST_OF_SEARCH, BROWSE).

countintegerrequired

The number of ads requested. Request more than the desired count to account for publisher-side filtering.

offsetintegerrequired

When requesting more ads for a query by a user, set this to the offset of the last ad shown to the user.

Use this when the user pages through search results and has seen all search ads in the previous response. Also use this when search ads in the previous response are ineligible for display (e.g., duplicates in the organic search).

Default value: 0

]

SPAAdRequest

{
  "id": "adb853c0-6df3-40e2-b243-efb1b56beb41",
  "type": "SEARCH",
  "user": {
    "id": "C785902B8150944B"
  },
  "device": {
    "ua": "Dalvik/2.1.0 (Linux; U; Android 7.0; SM-J701F Build/NRD90M)",
    "ip": "string",
    "os": "string",
    "osv": "string",
    "ifa": "string"
  },
  "app": {
    "id": "BR7NWI24B41Z6L",
    "name": "string",
    "domain": "string"
  },
  "site": {
    "id": "string",
    "name": "string",
    "domain": "string"
  },
  "query": "string",
  "query_lang": "string",
  "filters": [
    {
      "field": "brand_id",
      "value": [
        "260332020",
        "260332021"
      ],
      "type": "EQ"
    }
  ],
  "ordering": "RELEVANCE",
  "placement_requests": [
    {
      "placement": "string",
      "count": 0,
      "offset": 0
    }
  ]
}