API — Cognio System Integration Guide

DSP integration

1. Overview

This guide describes how to integrate an external DSP with the Cognio system to establish an interface connection based on the OpenRTB protocol.

2. Integration steps

Sign contract: a mutual agreement between Cognio and the DSP.
Register DSP account: contact the Cognio Operations PIC to register a DSP account and receive a token. Auto-registration is not currently supported, so you'll need to provide the relevant information to complete registration.
System integration set-up: follow this document to build the interface and set up the integration. A Product and Tech PIC will support any issues encountered.
Test: once set up, the DSP and Cognio arrange integration testing and make adjustments as needed.
Live: after testing, the Cognio business PIC follows up with the official launch of integrated traffic and begins recording cost.

3. Real-time bidding (RTB)

3.1 Data transmission

The connection follows the HTTP protocol. Bid Requests are sent via the POST method as the content of the HTTP request, in JSON format.

3.2 HTTP request

POST is used instead of GET, as it allows more content and better supports binary data.

Name	Value	Remarks
x-openrtb-version	2.5	OpenRTB version

3.3 HTTP response

If Cognio participates in the auction, the response status code is 200; otherwise it is 204.

3.4 Impression volume & cost calculation

Billing is based on impressions reported in the win notice (default is the nurl; if the DSP does not support nurl, the burl is used). You must replace the {AUCTION_PRICE} macro in the win-notice URL when a bid is won. At most one ad may be reported per impression, within the impression delay required by Cognio (limited via bidresponse.seatbid.bid.exp).

3.5 Precautions

If the following fields are empty, Cognio considers the request invalid and will not process it:

bid.device.geo.country — country of the user's network (ISO-3166-1-alpha-3)
bid.imp[].tagid — DSP's ad space identifier
bid.app.bundle — package name of the traffic source
bid.device.ifa — advertising identifier (Android: GAID, iOS: IDFA)
bid.device.ua — User-Agent from the device's HTTP header
bid.device.ip — IP address of the user's network

4.1 Bid Request

Parameter	Type	Required	Description
id	string	Yes	Unique identifier for the Bid Request
imp	object array	Yes	One impression object per request, representing a specific ad placement
app	object	Yes	App object info; recommended for app rather than website
device	object	Yes	Device info
user	object	No	Device user / ad audience
at	integer	Yes	Auction type: 1 = first-price, 2 = second-price plus
badv	string array	No	Domain blacklist
bapp	string array	No	App blacklist (Android: bundle/package names; iOS: numeric IDs)
regs	object	No	Applicable industry, legal, or governmental regulations

4.1.1 imp object

Parameter	Type	Required	Description
id	string	Yes	Identifier for the specific display traffic sold (one per request)
tagid	string	Yes	Fixed identifier of each ad placement
native	object	For native	Refer to native object
banner	object	For banner	Refer to banner object
video	object	For video	Refer to video object
audio	object	For audio	Refer to audio object
exp	integer	No	Seconds that may elapse between auction and display
secure	integer	No	1 = HTTPS required; 0/blank = not required
bidfloor	float	No	Minimum CPM bid price for this traffic
bidfloorcur	string	Yes	Bid currency; currently USD only

4.1.2 banner object

Parameter	Type	Required	Description
id	string	No	Unique identifier; recommended with video companion ads
w	integer	Yes	Width in device-independent pixels
h	integer	Yes	Height in device-independent pixels
pos	integer	No	Ad position on screen (see 5.5)
mimes	string array	Yes	Supported MIME types (e.g. image/jpg, image/png, image/gif)
ext	object	No	Exchange-specific extensions

4.1.3 native object

Parameter	Type	Required	Description
request	string	Yes	Must follow the native ad specification (see native request object)
ver	string	Yes	Dynamic Native Ads API version; default 1.2
api	integer array	No	Supported API frames (see 5.4)
battr	integer array	No	Restricted creative attributes (see 5.3)

4.1.4–4.1.9 native request, asset, title, img, video, data objects

Object	Key fields
native request	`assets` (object array, required), `ver` (default 1.2), `context` (see 5.10), `contextsubtype` (see 5.11)
asset request	`id` (required), `required` (1=must-have), and one of `title`/`img`/`video`/`data`
title	`len` — max title length (recommended 25/90/140 chars)
img	`type` (1=icon, 3=large), `wmin`/`hmin` required (pixels), `mimes`
video	`mimes` (video/mp4 only), `minduration`, `maxduration`, `protocols` (type 3 = VAST 3.0)
data	`type` (see 5.12), `len` — max characters

4.1.10 app object

Parameter	Type	Required	Description
id	string	No	Internal app ID
name	string	No	Internal app name
bundle	string	Yes	App package name
domain	string	No	App domain
cat	string array	No	IAB category (see 5.1)
ver	string	No	App version
DSP	object	Yes	DSP info (see DSP object)

4.1.11 DSP object

Parameter	Type	Required	Description
id	string	Yes	DSP ID, used to apply for token info
name	string	No	DSP name
domain	string	No	DSP's top-level domain
cat	string array	No	IAB category (see 5.1)

4.1.12 device object

Parameter	Type	Required	Description
ua	string	Yes	User-Agent of the device
ip	string	Yes	IPv4 address of the user's network
geo	object	Yes	Geographic info (see geo object)
didsha1 / didmd5	string	No	Hardware device ID (e.g. IMEI), hashed
dpidsha1 / dpidmd5	string	No	Platform device ID (e.g. Android ID), hashed
macsha1 / macmd5	string	No	Device MAC address, hashed
make / model	string	No	Device manufacturer / model
os / osv	string	Yes / No	Operating system and version
language	string	No	Device language (ISO-639-1-alpha-2)
connectiontype	integer	No	Network connection mode (see 5.8)
devicetype	integer	No	Device type (see 5.7)
w / h / ppi	integer	No	Screen width, height, pixels-per-inch
js	integer	No	JavaScript supported (0/1)
dnt	integer	No	Do Not Track (0 = not restricted, 1 = restricted)
lmt	integer	No	Limit ad tracking (0 = not restricted, 1 = restricted)
ifa	string	Yes	Advertising identifier (Android: GAID, iOS: IDFA)
mccmnc	string	No	Mobile network carrier

4.1.13 geo object

Parameter	Type	Required	Description
lat / lon	float	No	Latitude (-90 to +90) / longitude (-180 to +180)
type	integer	No	Source of geo info (see 5.13)
accuracy	integer	No	Accuracy in meters (when from GPS)
ipservice	integer	No	IP location provider, for type=2 (see 5.14)
country	string	Yes	Country code (ISO-3166-1-alpha-3)
region / city / zip	string	No	Region (ISO-3166-2), city (UN/LOCODE), postal code
utcoffset	integer	No	Local time offset from UTC, in minutes

4.1.14–4.1.16 user, data, segment objects

Object	Key fields
user	`id`, `buyeruid`, `gender` (M/F/0), `yob`, `keywords`, `geo`, `customdata`, `data`
data	`id` / `name` of data provider, `segment` (object array)
segment	`id`, `name`, `value` defined by the data provider

4.2 Bid Response

Parameter	Type	Required	Description
id	string	Yes	Matches the request id from the Bid Request
seatbid	object array	Yes	At least one SeatBid object if a bid is offered
bidid	string	No	Response ID for logs / tracking
cur	string	No	Currency (ISO-4217); default USD
ext	object	No	Bidder-specific extensions

4.2.1 seatbid object

Parameter	Type	Required	Description
bid	object array	Yes	At least one bid object; each maps to one impression
seat	string	No	Identifier of the bidder (advertiser/agency)
group	integer	No	0 = independent bids (default); 1 = win/fail as a group
ext	object	No	Bidder-specific extensions

4.2.2 bid object

Parameter	Type	Required	Description
id	string	Yes	Bid ID for logs / tracking
impid	string	Yes	ID of the related imp object
price	float	Yes	CPM price for the display
adid	string	No	Preloaded ad ID used on win
nurl	string	No	Win-notice URL
burl	string	Yes	Billing-notice URL; may include ${AUCTION_PRICE} macro
adm	string	Yes	Ad markup (native object or VAST for video)
adomain	string array	No	Advertiser domain, for filtering
bundle	string	For install ads	App package name
iurl	string	No	Image link for QC / security
cid / crid	string	No	Campaign ID / creative set ID for QC
cat	string array	Yes	IAB category of creative (see 5.1)
attr	integer array	No	Creative attributes (see 5.3)
api / protocol	integer	No	Supported API frame (5.4) / video protocol (5.6)
qagmediarating	integer	Yes	IQG media rating (see 5.9)
dealid	string	No	Deal ID for private marketplace deals
w / h	integer	No	Creative width / height (pixels)
exp	integer	No	Seconds the bidder will wait before display (default 3600)
ext	object	No	Bidder-specific extensions

4.2.3–4.2.9 native ad response objects

Object	Key fields
native ad response	Stored in `adm`; `ver`, `assets` (required), `link` (required), `imptrackers` (required), `ext`
asset response	`id` (matches request), `required`, one of `title`/`img`/`video`/`data`
title	`text` (required), `len`
img	`url` (required), `w`/`h` (required), `type` (1=icon, 3=large)
data	`value` (required), `type`/`label` (see 5.12)
video	`vasttag` — video content in VAST format
link	`url` (required landing URL), `clicktrackers`, `ext`

SSP integration

The SSP (publisher) integration follows the same OpenRTB transmission rules, Bid Request / Bid Response structure, and enumerated values as the DSP spec above. The key difference is that the app.publisher object replaces the app.DSP object.

Integration steps (publisher)

Sign contract: mutual agreement between Cognio and the Publisher.
Register publisher account: contact the Cognio Operations PIC to register and receive a token (no auto-registration).
System integration set-up: build the interface per this document, with Product and Tech PIC support.
Test: arrange integration testing and adjust as needed.
Live launch: the Cognio business PIC follows up with official launch and begins recording cost.

publisher object (replaces DSP object)

Parameter	Type	Required	Description
id	string	Yes	Publisher ID, used to apply for token info
name	string	No	Publisher name
domain	string	No	Publisher's top-level domain
cat	string array	No	IAB category (see 5.1)

Note: on the SSP side, our system supports one seatbid object per response, and one bid per seatbid.

5. Enumerated value lists

5.1 IAB category (top-level)

Creatives and inventory are classified using the IAB Content Taxonomy. Top-level categories are below; the full sub-category list (e.g. IAB2-1 Auto Parts) follows the standard IAB taxonomy.

Value	Category	Value	Category
IAB1	Arts & Entertainment	IAB14	Society
IAB2	Automotive	IAB15	Science
IAB3	Business	IAB16	Pets
IAB4	Careers	IAB17	Sports
IAB5	Education	IAB18	Style & Fashion
IAB6	Family & Parenting	IAB19	Technology & Computing
IAB7	Health & Fitness	IAB20	Travel
IAB8	Food & Drink	IAB21	Real Estate
IAB9	Hobbies & Interests	IAB22	Shopping
IAB10	Home & Garden	IAB23	Religion & Spirituality
IAB11	Law, Government & Politics	IAB24/25	Uncategorized / Non-Standard
IAB12	News	IAB26	Illegal Content
IAB13	Personal Finance

5.2 Banner ad type

Value	Description
1	XHTML Text Ad (usually mobile)
2	XHTML Banner Ad (usually mobile)
3	JavaScript Ad; must be valid XHTML (script tags included)
4	iframe

5.3 Creative attribute

Value	Description
1 / 2	Audio Ad (Auto-Play / User Initiated)
3 / 4 / 5	Expandable (Automatic / Click / Rollover)
6 / 7	In-Banner Video Ad (Auto-Play / User Initiated)
8	Pop (Over, Under, or Upon Exit)
9	Provocative or Suggestive Imagery
10	Shaky, Flashing, Flickering, Extreme Animation, Smileys
11	Surveys
12	Text Only
13	User Interactive (e.g. embedded games)
14	Windows Dialog or Alert Style
15	Has Audio On/Off Button
16	Ad Provides Skip Button
17	Adobe Flash

5.4 API frame

Value	Description
1 / 2	VPAID 1.0 / 2.0
3	MRAID-1
4	ORMMA
5 / 6	MRAID-2 / MRAID-3

5.5 Ad placement / position

Value	Description
0	Unknown
1	Above the Fold
2	Deprecated — may or may not be initially visible
3	Below the Fold
4 / 5 / 6	Header / Footer / Sidebar
7	Full Screen

5.6 Video bid response protocol

Value	Description
1 / 2 / 3	VAST 1.0 / 2.0 / 3.0
4 / 5 / 6	VAST 1.0 / 2.0 / 3.0 Wrapper
7	VAST 4.0
8	DAAST 1.0

5.7 Device type

Value	Description
1	Mobile/Tablet (v2.0)
2	Personal Computer (v2.0)
3	Connected TV (v2.0)
4 / 5	Phone / Tablet (v2.2)
6	Connected Device (v2.2)
7	Set Top Box (v2.2)

5.8 Network connection mode

Value	Description
0	Unknown
1 / 2	Ethernet / WIFI
3	Cellular — Unknown Generation
4 / 5 / 6 / 7	Cellular 2G / 3G / 4G / 5G

5.9 IQG media rating

Value	Description
1	All Audiences
2	Everyone Over 12
3	Mature Audiences

5.10 / 5.11 Context type & sub-type

Value	Description
1	Content-centric (newsfeed, article, gallery, video)
2	Social-centric (social feed, email, chat)
3	Product context (listings, details, reviews)
10–15	Sub-types: general, article, video, audio, image, UGC
20–22	Sub-types: social network, email, chat/IM
30–32	Sub-types: selling products, app marketplace, product reviews

5.12 Data asset type

ID	Name	Description
1	sponsored	"Sponsored By" message — brand name of the sponsor
2	desc	Descriptive text for the product/service
3	rating	Rating of the product (e.g. 0–5)
4	likes	Number of social ratings / likes
5	downloads	Number of downloads / installs
6	price	Price (include localized currency symbol)
7	saleprice	Sale price (with price, to show a discount)
8 / 9	phone / address	Phone number / address
10	desc2	Additional descriptive text
11	displayurl	Display URL for the text ad
12	ctatext	Call-to-action description

5.13 / 5.14 Location type & IP location services

Value	Description
Location 1 / 2 / 3	GPS / IP Address / User provided
IP 1–4	ip2location / Neustar (Quova) / MaxMind / NetAcuity (Digital Element)

To register a DSP or SSP account and request a token, contact commercial@thecognio.com.

Migrated from Cognio's previous site. The full IAB sub-category taxonomy from the original page was consolidated to top-level categories here — paste the complete sub-category table back in if you need it verbatim for partner reference.

Cognio System Integration Guide

On this page