Skip to content

Latest commit

 

History

History
1770 lines (1587 loc) · 35.6 KB

version2.en.md

File metadata and controls

1770 lines (1587 loc) · 35.6 KB
Raw

fluct RTB Specification ver 2.6

This specification complies with OpenRTB Version 2.6.

See IAB OpenRTB API Specification Version 2.6 for details.

Attention

This specification may be incomplete. If you find any inadequacy or encounter confusion, please contact the person in charge: [email protected].

Moreover, this specification does not contain description of general RTB protocol (e.g., OpenRTB).

Table of Contents

1. Cookie Sync

Usually the following sync will be performed, however we are also able to provide specified flows separately.

  1. SSP delivers sync image tags of DSP to ad inventories.
  2. DSP redirects to SSP’s sync URL when received access to sync tag.
  3. DSP adds an ID parameter to sync URL as a notification to SSP.

DSP should prepare sync tags for SSP in advance. (DSP reponsibility)

Currently we only support image sync tags and https requests.

Below is an example of sync URLs of fluct. HTTPs sync is also supported.

https://cs.adingo.jp/sync/?from=[DSP_NAME]&id=[DSP_USER_ID]

The DSP_NAME parameter will be provided by SSP beforehand (SSP responsibility), please contact SSP for that.

The expiry date of sync is default to 30 days, however it can also be customized to any length. Below is an example of a sync with 90 days of expiry date.

https://cs.adingo.jp/sync/?from=your_dsp&id=XXXXXX&expire=90

2. Request/Response Encoding

To minimize HTTP traffic exchanged between DSP and Fluct, it is recommended to have both bid request and response bodies compressed.

a. Request Encoding

Bid requests can be gzip-compressed. If DSPs wish to receive gzip-compressed bid requests, contact an alliance representative.

Following header is added to a request when its body is gzip-compressed:

Content-Encoding: gzip

b. Response Encoding

A response body can be compressed when its request has a header similar to:

Accept-Encoding: gzip

When returning a compressed response body, such response should have a header similar to:

Content-Encoding: gzip

3. Request Specification

a. Endpoint URL

The endpoint URL which will be used by bid request should be passed to SSP. (DSP reponsibility)

SSP conducts bid request with POST method to the specified endpoint URL.

For the optimal performance, DSP should enable HTTP keep-alive whenever possible.

https request is also supported.

Please let us know if we need to set the specific Port.

b. OpenRTB Version HTTP Header

The OpenRTB Version of the request will be passed in bid request HTTP header as:

X-OpenRTB-Version: 2.5

The version is in format <major>.<minor>, and patch version is not included.

Fluct will follow backward-compatible OpenRTB 2 minor version updates, and the version in HTTP header will be updated, accordingly.

c. Bid Request Throttling

Bid request QPS is controlled based on the ratio of response errors (HTTP status code 500 or above, or receive timeout) per unit time.

As error responses increase, the bid request QPS will be gradually decreased. Contrarily, as such responses decrease, the QPS will be gradually increased.

d. Bid Request Parameters

Serialization format: JSON only.

Bid Request Object (Top Level)

Field Type Description
id string; required
imp array of imp objects; required
site site object
app app object
user user object
bcat array of strings; required
tmax integer auction timeout in msec
device device object
at integer 1=first price auction, 2=second price auction
wseat array of strings Whitelist of buyer seats
cur array of strings a list of accepted currencies
  • Only one of the "site" and “app” sections will be necessary.

imp Object

Field Type Description
id string; required
tagid string; required ex) 1234:987654321
secure integer
banner banner object
video video object
native native object
pmp pmp object
instl integer 0=no, 1=yes
bidfloor float Floor price
bidfloorcur string Floor price currency
rwdd integer Whether the viewer receives a reward for viewing the ad. 0=no, 1=yes
ext imp.ext object imp extension object

imp.ext Object

Field Type Description
dfp_ad_unit_code string; experimental Google AdManager Ad unit full path
skadn skadn Request object SKAdNetwork request object
gpid string Global Placement ID

source Object

Both Sellers.json and OpenRTB SupplyChain are available.

Refer to https://adingo.jp/sellers.json for sellers available through fluct.

Field Type Description
fd integer; required 1 when upstream source is responsible for the final impression sale decision, or 0 otherwise.
tid string; experimental Transaction ID that is issued by upstream. Otherwise, same as BidRequest.id.
schain supply-chain object OpenRTB SupplyChain object
ext source.ext object source extension object

source.ext Object

Field Type Description
stype string; experimental Header Bidding type. Contact us for details.

site Object

Field Type Description
id string; required
cat array of strings
domain string
page string; required
mobile integer Indicates if the layout is optimized for mobile devices. 0=No, 1=Yes
publisher publisher object

app Object

Field Type Description
id string; required
cat array of strings
storeurl string
bundle string Platform-specific application identifier. ex) Android: "com.foo.mygame", iOS: "1234567890"
publisher publisher object

publisher Object

Field Type Description
id string; required

user Object

Field Type Description
id string
buyeruid string
gender string "M" or "F"
yob integer
eids array of objects User EID Objects
data array or objects User Data Objects
  • When "ifa" is sent, “user.buyeruid” is not sent and “user.id” is set to be the value of “device.ifa”.

device Object

Field Type Description
ua string; required
sua object UserAgent Object
geo geo object
ip string IPv4 Address
ipv6 string IPv6 Address
ifa string
lmt integer
dnt integer
osv string
h integer screen height in pixels
w integer screen width in pixels
  • When device.w and device.h are available, screen orientation can be determined as:
    • when w > h: landscape
    • when h > w: portrait

geo Object

Field Type Description
lat float Latitude; -90.0~90.0 where negative is south
lon float Longitude; -180.0~180.0 where negative is west
Type integer Source of location data; 1=GPS, 2=IP address, 3=User provided
accuracy integer Accuracy in meters
ipservice integer Provider of IP address geolocation service; 1=ip2location, 2=Neustar, 3=MaxMind, 4=NetAcuity
country string Country code in ISO 3166-1 alpha-3
region string Region code in ISO 3166-2; 2-letter state code if US
metro string Google metro code
city string City name
zip string Zip or postalcode
utcoffset integer Local time offset from UTC in minutes

banner Object

Field Type Description
format array of format objects
h integer Specified only when exactly 1 object exists in format array.
w integer Specified only when exactly 1 object exists in format array.
pos integer; required 0=unknown, 1=above the fold, 3=below the fold
vcm integer Relavant only for banner objects in imp.video.companionad. 0=concurrent, 1=end-card

format Object

Field Type Description
h integer; required height
w integer; required width

video Object

Field Type Description
mimes array of strings; required "video/mp4"
pos integer 0=unknown, 1=above the fold, 3=below the fold
minduration integer
maxduration integer
protocols array of integers
battr array of integers
h integer
w integer
startdelay integer 0=pre-roll, >0=mid-roll, -1=mid-roll, -2=post-roll
linearity integer 1=in-stream 2=overlay
minbitrate integer
maxbitrate integer
skip integer 0=no, 1=yes
api array of integers
placement integer
companionad array of banner objects Array of banner objects when supported.
companiontype array of integers 1=static resource, 2=HTML resource, 3=iframe resource
delivery array of integers
podseq integer -1=Last pod in the content stream, 0=Any pod in the content stream, 1=First pod in the content stream
poddur integer Duration of the pod in seconds for a dynamic ad pod.
maxseq integer Maximum number of ads served in a dynamic ad pod.
rqddurs array of integers Acceptable creative durations in seconds for a dynamic ad pod.

audio Object

Field Type Description
mimes array of strings; required "audio/mp4"
minduration integer
maxduration integer
protocols array of integers 1=VAST 1.0, 2=VAST 2.0, 3=VAST 3.0, 4=VAST 1.0 Wrapper, 5=VAST 2.0 Wrapper, 6=VAST 3.0 Wrapper, 7=VAST 4.0, 8=VAST 4.0 Wrapper
startdelay integer 0=pre-roll, >0=mid-roll, -1=mid-roll, -2=post-roll
battr array of integers
minbitrate integer
maxbitrate integer
api array of integers 1=VPAID 1.0, 2=VPAID 2.0, 3=MRAID-1, 4=ORMMA, 5=MRAID-2
feed integer 1=Music Service, 2=FM/AM Broadcast, 3=Podcast
stitched integer 0=no, 1=yes
companionad array of banner objects Array of banner objects when supported.
companiontype array of integers 1=static resource, 2=HTML resource, 3=iframe resource
podseq integer -1=Last pod in the content stream, 0=Any pod in the content stream, 1=First pod in the content stream
poddur integer Duration of the pod in seconds for a dynamic ad pod.
maxseq integer Maximum number of ads served in a dynamic ad pod.
rqddurs array of integers Acceptable creative durations in seconds for a dynamic ad pod.

native Object

Field Type Description
request string; required fluct Native Ads Spec
ver string
api array of integers List of supported API frameworks for this impression
battr array of integers Blocked creative attributes

pmp Object

Field Type Description
private_auction integer; required
deals array of deal objects; required

deal Object

Field Type Description
id string; required
at integer 1=first price auction, 2=second price auction, 3=fixed price
bidfloor float Floor price when "at" is 1 or 2, deal price when "at" is 3
bidfloorcur string Floor price currency
wseat array of strings Whitelist of buyer seats
wadomain array of strings Whitelist of advertiser domains
ext deal.ext object deal extension object

deal.ext object

Field Type Description
publisher_blocks_overridden int Whether bid to the deal should ignore bcat. 0=false, 1=true

skadn Request Object

SKAdNetwork Request Object

Field Type Description
version string; required Version of SKAdNetwork supported. Always "2.0" or higher.
sourceapp string; required Platform-specific application identifier. ex) iOS: "1234567890"
skadnetids array of strings; required SKAdNetworkItem entries in the publisher app's info.plist

User EID Object

Extended Identifiers

Field Type Description
source string Ad system identifier
uids array of objects User UID Object

User UID Object

Field Type Description
id string
atype integer 1=tied to web browser or device (cookie-based, probabilistic, or other), 2=in-app impression typically containing device ID, 3=person-based ID
ext object

User Data Object

Field Type Description
name string
segment array of objects User Data Segment Object
ext object User Data Ext Object

User Data Segment Object

Field Type Description
id string

User Data Ext Object

Field Type Description
segtax integer

UserAgent Object

Field Type Description
browsers array of objects See BrandVersion Object
platform object See BrandVersion Object

BrandVersion Object

Field Type Description
brand string
version array of strings

4. Response Specification

a. Bid Response Parameters

DSP should serialize bid information with the JSON format.

HTTP 204 No Content is expected for no bid.

Bid Response Object (Top Level)

Field Type Description
id string; required ID of bid response
cur string; required Bid price currency using ISO-4217 code
seatbid array of seatbid objects; required 1+ seatbid objects

seatbid Object

Field Type Description
bid array of bid objects; required 1+ bid objects
seat string ID of the buyer seat. Required when bidding for multiple seats.

bid Object

Field Type Description
impid string; required Bid target BidRequest.imp.id
price float; required Bid price
adm string; required Ad markup data. Substituting macros may be included. See response example for details.
adomain array of strings; required A list of advertiser domains. When not returned, the bid to a frame where a publisher blocks advertisers by domain is invalid.
bundle string; recommended Platform-specific application identifier. ex) Android: "com.foo.mygame", iOS: "1234567890"
cid string; recommended Campaign ID
crid string; recommended Creative ID
dealid string Required if bidding for a PMP deal. Reference to BidRequest.imp.pmp.deal.id
h integer; recommended Creative height in pixels
w integer; recommended Creative width in pixels
attr array of integers; recommended Creative Attributes. See IAB OpenRTB 2.5 specification 5.3 Creative Attributes for details.
cat array of strings; recommended Creative Categories. See IAB OpenRTB 2.5 specification 5.1 Content Categories for details.
nurl string Win notice URL to be called if the bid wins the auction. Not necessarily indicating delivered, viewed, or billable. Substituting macros may be included.
lurl string Loss notice URL to be called if the bid loses the auction. Substituting macros may be included.
dur integer Duration of the video or audio creative in seconds. Required when bidding on a dynamic ad pod.
mtype integer; recommended Type of the creative markup. 1=Banner, 2=Video, 3=Audio, 4=Native
ext bid.ext Object bid extension object

bid.ext Object

Field Type Description
skadn skadn Response object SKAdNetwork response object
clicktrackers array of strings Click trackers for SKAdnetwork response object

skadn Response Object

SKAdNetwork Response Object

Field Type Description
version string; required Version of SKAdNetwork desired. 2.0 or above.
network string; required Should be one of `BidRequest.imp.ext.skadn.skadnetids`.
campaign string; required Campaign ID compatible with Apple’s spec.
itunesitem string; required Advertiser app's Apple App Store ID. Should match `BidResponse.seatbid.bid.bundle`.
nonce string; required Unique ID for each ad response
sourceapp string; required Platform-specific application identifier. Should match `BidRequest.imp.ext.skadn.sourceapp`.
timestamp string; required Unix time in milliseconds in string.
signature string; required Apple SKAdNetwork signature.

b. Impression/Click Beacon

The following assumptions are made about URLs which serve beacons:

Endpoint for Impression Beacon

  • GET method support

  • sent by setting URL in src field on img tag (XMLHttpRequest not supported)

fluct transmits according to the following conditions (imp beacon):

endpoint (URL) specified in the bid response
HTTP method GET

Endpoint for Click Beacon

  • HTTPS (TLS version 1.2 or above) support
  • POST support
  • Cross-Origin XMLHttpRequest support (see definition at http://www.w3.org/TR/cors/)

fluct transmits according to the following conditions (click beacon):

endpoint (URL) specified in the bid response
HTTP method POST
Origin origin of tranmission
Access-Control-Allow-Credentials true
Accept */*
  • It is assumed that transmission is done from the browser which delivers the advertisement; hence Cross-Origin XMLHttpRequest is used.
  • For some environments navigator.sendBeacon() (as defined at http://www.w3.org/TR/beacon/) is also transmitted.

c. Macro Substitution

Macro Description adm nurl lurl
${CLICK_URL_ENC} (To Be Removed on 2020/12/31) End of CLICK_URL_ENC Macro Support Yes
${AUCTION_CURRENCY} Currency code used in the bid. Yes Yes Yes
${AUCTION_ID} Auction ID from bid request id. Yes Yes Yes
${AUCTION_IMP_ID} Impression ID from bid request imp.id. Yes Yes Yes
${AUCTION_LOSS} Auction loss reason codes. See IAB OpenRTB 2.5 specification 5.25 Loss Reason Codes for details. Yes Yes
${AUCTION_PRICE} Auction clearing price. Encryption is optional. Substituted to AUDIT in the creative review process. Yes Yes Yes
${AUCTION_PRICE_IV} Initialization vector (IV) for the auction clearing price encryption. Substituted when the encryption algorithm requires IV generation. Yes Yes Yes
${AUCTION_SECOND_PRICE} Auction second price. Encryption is optional. Yes Yes
${AUCTION_SECOND_PRICE_IV} Initialization vector (IV) for the auction second price encryption. Substituted when the encryption algorithm requires IV generation. Yes Yes
${IS_PREVIEW} Substituted to 1 in the creative review pricess, otherwise substituted to 0. Yes
  • Cipher system (algorithm, key length, block cipher modes of operation) should be decided beforehand. (e.g., CFB 3DES + the so called Web safe Base64 etc.)
    • Fluct issues the encryption key after cipher system has been determined.
  • Unless otherwise specified, macros are not substituted during the creative review process.
  • Additional macros may be implemented when demanded.

d. End of CLICK_URL_ENC Macro Support

As a part of the systems improvement, Fluct is going to drop support for the Fluct-defined click-measurement macro, ${CLICK_URL_ENC}, on December 31, 2020. After the date, the ad click-through may not navigate viewer browser to the landing page if the macro exists in the ADM. In order to prevent unexpected click behavior, please remove the macro completely before the date.

5. Code Table

6. Bid Request/Response Examples

Request Examples

See version2.req-examples.md for details.

Response Examples

See version2.res-examples.md for details.

7. iOS 14 Click Logic

When DSP returns skadn object with a valid itunesitem, fluct's iOS SDK supports below special click logic in addition to regular click logic. Please also see clicktrackers in bid.ext.

Video

  • Fluct supports click tracking through the VAST <ClickThrough>, and we stop redirecting once we reach non-redirect response.
  • Fluct supports click tracking through the VAST <CompanionClickThrough>, and we stop redirecting once we reach non-redirect response.
  • The same logic applies for static, iFrame and HTML end cards.

Display

  • Fluct supports click tracking through click through URL, and we stop redirecting once we reach non-redirect response.