Tapjoy OpenRTB Specification

1. Introduction

This document outlines how DSPs can integrate with Tapjoy using the OpenRTB 2.5 specification.

A. Tapjoy Network Details

Tapjoy’s servers are located in AWS US_EAST (Virginia) only. We recommend DSP partners have their servers located near this location to ensure latency is minimised. We support a max tmax of 400ms across all regions.

For our latest QPS, please reach out to your Tapjoy contact for the most up to date numbers.

Tapjoy does not currently support gzip requests. Please get in touch with our team if this is something you would like us to consider adding support for.

Tapjoy requires the use of HTTPS for transactions and we use POST for all transactions. If you require GET, please let us know.

2. Requests

Tapjoy supports OpenRTB 2.5, supported bid request parameters can be found below:

Field Name	Description
BidRequest
id	Tapjoy defined unique id
bcat	IAB blocked categories
tmax	This will vary based on network latency
at	We support first price auction, value: 1
bapp	We support app bundle based blocklisting
badv	We support advertiser domain based blocklisting
Impression	We send across only a single video impression object.
imp[0].instl	Always set to 1
imp[0].bidfloor	As CPM in USD
imp[0].secure	Always set to 1, we support only https.
imp[0].id
imp[0].ext.rewarded	Tapjoy Extension to indicate if this is a rewarded inventory. Value: 0 = not rewarded. Value: 1 = rewarded.
imp[0].ext.skadn	Support for Apple’s SKAdNetwork
imp[0].ext.skadn.version	Supported version of SKAdNetwork
imp[0].ext.skadn.sourceapp	Publisher’s app bundle. Should be the same as app.bundle
imp[0].ext.skadn.skadnetids	A subset of ids that are relevant to the DSP
Banner Impression	*Currently Tapjoy only supports MRAID for the banner object
imp[0].banner.format..w
imp[0].banner.format.h
imp[0].bannero.w
imp[0].banner.h
imp[0].banner.pos
imp[0].banner.api	3,5 supported
imp[0].banner.id
imp[0].banner.ext.placementtype	Supported placement type
imp[0].banner.ext.allowscustomclosebutton	does this request support MRAID's customClose
Video Impression
imp[0].video.mimes	Tapjoy supports mp4, webm (android only)
imp[0].video.maxduration	Tapjoy supports 30 seconds
imp[0].video.protocols	We support vast 2,3 and wrappers i.e. 2,3,5,6
imp[0].video.w
imp[0].video.h
imp[0].video.pos
imp[0].video.skip	Skippable video is supported
imp[0].video.maxbitrate
imp[0].video.playbackmethod	Only 1,3,5 are supported
Companion Ad
imp[0].video.companiontype	We currently support 1(static resource).
imp[0].video.companionad
imp[0].video.companionad[0].w
imp[0].video.companionad[0].h
imp[0].video.companionad[0].id
imp[0].video.companionad[0].w
imp[0].video.companion
App
app.id	Encrypted Tapjoy internal appid
app.name	App Name
app.bundle	Bundle ID or Store ID
app.publisher.id	the publisher id used for app-ads.txt entries
Device
device.ua	User Agent string
device.geo.type	ip-address-based
device.geo.ipservice	maxmind
device.country	ISO-3166-1-alpha-3 standard
device.region
device.city
device.lmt	Limit Ad Tracking
device.ip	Device IP
device.ipv6	Device IPv6 if available
device.devicetype	phone/tablet/phablet
device.make	Device make
device.model	Device model
device.os	Ios or Android
device.osv	Version of OS
device.language	Content language using ISO-639-1-alpha-2
device.connectiontype	wifi/mobile/2g/3g/4g
device.ifa	IDFA or GAID if available
device.ifv	IDFV, available on iOS only. Use of this identifier by DSPs must be aligned with Apple’s User Privacy and Data Use policy.
Source
source.fd	Always set to 1
source.tid	Transaction ID common across all participants in this bid request (e.g., potentially multiple exchanges).
source.pchain	Supported
source.ext.header_bidding	0 - waterfall, 1 - header_bidding
source.ext.mediator_id	hashed string of the mediator name
source.ext.omidpn	Identifier of the OM SDK integration. The default value is "tapjoy"
source.ext.omidpv	IIdentifier of the Open Measurement (OM) SDK version
Source.ext.schain
source.ext.schain.complete	Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app or other medium of the inventory, where 0 = no, 1 = yes.
source.ext.schain.nodes
source.ext.schain.ver	Version of the supply chain specification in use
Source.ext.schain.nodes
source.ext.schain.nodes.asi	The canonical domain name of the SSP, Exchange, Header Wrapper, etc system that bidders connect to.
source.ext.schain.nodes.sid	The identifier associated with the seller or reseller account within the advertising system.
source.ext.schain.nodes.rid	The OpenRTB RequestId of the request as issued by this seller.
source.ext.schain.nodes.hp	Indicates whether this node will be involved in the flow of payment for the inventory.
Regs
regs.coppa	Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.
regs.ext.us_privacy	Currently used to send CCPA status. Please refer to IAB docs for more information about this flag.
reg.ext.gdpr	The GDPR regulation parameter is passed to indicate if the request is subject to GDPR regulation, where 0 = No, request is not subject to GDPR, and 1 = Yes, request is subject to GDPR
User
user.consent

A. Sample Request

{
  "id": "3f6a1327-2524-4c29-859e-fdc7a627cbea",
  "imp": [
    {
      "id": "1",
      "banner": {
        "format": [
          {
            "w": 406,
            "h": 722
          },
          {
            "w": 320,
            "h": 480
          }
        ],
        "w": 406,
        "h": 722,
        "api": [
          3,
          5
        ],
        "id": "1",
        "ext": {
          "placementtype": "interstitial",
          "allowscustomclosebutton": false
        }
      },
      "video": {
        "mimes": [
          "video/mp4"
        ],
        "maxduration": 35,
        "protocols": [
          2,
          3,
          5,
          6
        ],
        "w": 406,
        "h": 722,
        "placement": 5,
        "skip": 1,
        "skipafter": 5,
        "maxbitrate": 2000,
        "playbackmethod": [
          1,
          3
        ],
        "companionad": [
          {
            "w": 406,
            "h": 722,
            "id": "1"
          }
        ],
        "api": [
          7
        ],
        "companiontype": [
          1
        ],
        "ext": {
          "placementtype": "interstitial",
          "orientation": "v",
          "skip": 1,
          "skipdelay": 5
        }
      },
      "displaymanager": "Tapjoy SDK",
      "displaymanagerver": "12.8.1",
      "instl": 1,
      "bidfloor": 0.8760000000000001,
      "secure": 1,
      "ext": {
        "rewarded": 0,
        "skadn": {
          "version": "2.2",
          "versions": [
            "2.0",
            "2.1",
            "2.2"
          ],
          "sourceapp": "1028166062",
          "skadnetids": [
            "ecpz2srf59.skadnetwork"
          ]
        }
      }
    }
  ],
  "app": {
    "id": "1af1c4cc1164cfebc58cb988473832680a4ee832f475345c934a38e09b504473fd6f8f58be1042f1bb1e8764a9e3ba63",
    "name": "The Void Walker",
    "bundle": "1028166062",
    "publisher": {
      "id": "698435044ffd4adc940a9f57172d62c3"
    },
    "ext": {
      "appstoreid": "1028166062"
    }
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
    "geo": {
      "lat": 37.774929,
      "lon": -122.419418,
      "type": 2,
      "ipservice": 3,
      "country": "USA",
      "region": "CA",
      "city": "San Francisco",
      "utcoffset": 420
    },
    "dnt": 0,
    "lmt": 0,
    "ip": "1.55.251.0",
    "devicetype": 4,
    "make": "Apple",
    "model": "iPhone8,2",
    "os": "ios",
    "osv": "14.7.1",
    "hwv": "iPhone8,2",
    "h": 2208,
    "w": 1242,
    "pxratio": 3.05625,
    "js": 1,
    "connectiontype": 0,
    "ext": {
      "atts": 2,
      "audiovolume": 0,
      "ifv": "12345678-AAAA-BBBB-CCCC-12345678901"
    }
  },
  "user": {},
  "at": 1,
  "tmax": 674,
  "bcat": [
    "IAB11",
    "IAB9-5",
    "IAB11",
    "IAB9-9",
    "IAB7-39",
    "IAB23",
    "IAB25",
    "IAB26",
    "IAB8-18",
    "IAB8-5"
  ],
  "badv": [
    "tapjoy.com"
  ],
  "bapp": [
    "1028166062"
  ],
  "source": {
    "fd": 1,
    "tid": "fa7ff2a0-f3ac-4a77-9575-08d911500d47",
    "pchain": ":698435044ffd4adc940a9f57172d62c3",
    "ext": {
      "omidpn": "Tapjoy",
      "omidpv": "1.3.15"
    }
  },
  "regs": {}
}

3. Responses

Tapjoy supports OpenRTB 2.5, supported bid response parameters can be found below:

Field Name	Description
BidResponse
id	Response ID
bidid	Id for logging and monitoring
nbr	Not used
Seatbid
bid	We only use the first bid provided in this array.
Bid[0]
id	Required
impid	Required should match bid request id
price	Required, only USD format accepted as CPM.
adid	Debugging and logging
adm	Should not be encoded.
adomain	Required. Domain like ford.com
bundle	Bundle of the app
cid	Debugging and logging
crid	Required ( we blocklist creatives by this id, which fail to render )
cat	IAB category
attr	Type of AD
Ext
imptrackers	Array of urls that will be called at ad-render, we support a maximum of 5 urls.
skadn	Parameters needed to support Apple’s SKAdNetwork API to call loadProduct()
skadn
version	Version of SKAdNetwork desired
network	The network identifier
campaign	Campaign ID, should be between 1 and 100
itunesitem	Advertiser’s App store ID
nonce	Unique ID. Refer to Apple’s documentation.
sourceapp	ID of publisher app
timestamp	Unix time in millis string
signature	SKAdNetwork signature. Refer to Apple’s documentation.

4. Impression Tracking

Tapjoy prefers the use of bid.burl to trigger the impression event, however, Tapjoy does also support URLs in the bid response in the ext.imptrackers field. Tapjoy defaults to using a POST method for these, so if you need to use GET, please let us know.

For ‘imptrackers’ support, DSPs need to use the following impression extension in the bid response: seatbid[].bid.ext.imptrackers. We will fire the burl and not the imptrackers if burl exists for both video and display.

Impression events are triggered during ad-render.

5. Loss Notifications

When a lurl is provided in the bid response, Tapjoy will fire this URL via a server-side POST request. However, you must reach out to your Tapjoy contact to have this enabled for you first, as this is not enabled by default.

A. Macro Substitutions

This is the list of macro substitutions that Tapjoy supports.

Macro	Description
${AUCTION_PRICE}	The settlement price of the auction. This macro is required in any bid response, otherwise the bid is considered invalid.
${AUCTION_MINIMUM_BID_TO_WIN}	Currently only returns the winning bid price.
${AUCTION_LOSS}	Loss reason codes. Refer to list list below.
${AUCTION_ID}	ID of the bid request; From BidRequest.id attribute
${AUCTION_BID_ID}	ID of the bid; From BidResponse.id attribute
${AUCTION_IMP_ID}	ID of the impression won. From imp.id attribute
${AUCTION_SEAT_ID}	ID of the bidder seat for whom the bid was made
${AUCTION_AD_ID}	ID of the ad markup the bidder wishes to serve; from the bid.adid attribute
${AUCTION_CURRENCY}	The currency used in the bid. Tapjoy only supports USD

B. Loss Values

Value	Description
1	Internal Error
3	Invalid Bid Response
102	Lost to a higher Bid
200	Creative filtered. Generally because we have seen high errors from this creative

6. Creative Requirements

Tapjoy supports full screen interstitial ad rendering, for display (fullscreen MRAID only) and video (skippable interstitial or rewarded). Creative details of each available impression is passed in the bid request. Companion ads are also supported alongside video creatives, and can contain a single, static resource.

To determine whether an impression opportunity is rewarded or non rewarded, please use the imp[0].ext.rewarded flag in the bid request, where 0 = not rewarded and 1 = rewarded.

A. VAST Requirements

All video content is served via VAST, with versions 2.0 and 3.0 (both InLine and Wrapper) supported for linear, skippable and companion ads.

If using OpenRTB protocols, this translates to the supported values of 2, 3, 5 and 6.

Additional ad requirements which need to be observed are:

Video format: MP4
Video file size limit: 5 MB
Orientations supported: Landscape and vertical video
Max video length: 30 seconds
Min video length: 6 seconds

Companion ads are often used as the video end card and are supported alongside video creatives. They show after the video completion and can contain a single, static resource. The should be placed in the "companion ad" object of the VAST tag as an image file + click-though URL. Accepted file formats are .JPEG, .PNG, .GIF. All sizes are allowed, however, the max size allowed is 1024x1024. The most popular sizes are: 480x320, 300x250, 1024x768.

B. MRAID Requirements

MRAID support is limited to versions 2.0 and 3.0.

Tapjoy will always use our own close button, so we will send “useCustomClose” as false always.

Static MRAIDs are allowed, but only for interstitial/non-rewarded requests.

Tapjoy supports the following methods:

Methods Description	Description	Support
getVersion	ad checks the version of the MRAID implementation that the host is using.	yes
addEventListener	ad registers a listener for a specified event	yes, see events section below for details
removeEventListener	ad removes a listener for a specified event	yes
open	ad specifies a URL to be opened in a new webview	yes
close	ad calls to downgrade the state ad container	yes
useCustomClose	deprecated in MRAID 3.0. This method call will be ignored by MRAID 3.0 compliant hosts	no
unload	ad calls to dismiss or remove the webview because it cannot load or render the assets. Host can either remove the webview, replace with another document or refresh with a new ad call
isViewable	ad queries the host about the on-screen status of the ad container	yes
playVideo	ad requests video play in native player resize ad requests ad container size change to accommodate new ad size	no
storePicture	ad requests prompt to user about storing a picture on the device	No
createCalendarEvent	ad request prompt to the user for adding an event to the device calendar	No
expand	ad requests ad container expansion	No
supports	ad requests details on features the host supports (see special section below)	yes, see support section below for details
getPlacementType	ad requests confirmation of either an inline or interstitial placement	yes
getOrientationProperties	ad requests details on landscape or portrait orientation	yes
setOrientationProperties	ad specifies preferences for allowing or locking orientation, if supported, for ad display	yes
getCurrentAppOrientation	ad requests current orientation of the app	no
getCurrentPosition	ad requests current coordinates of the ad container	yes
getDefaultPosition	ad requests default coordinates of the ad container	yes
getState	ad requests current state of the ad container: loading, default, expanded, resized, hidden
resize		no
getExpandProperties	ad requests current expand properties	no
setExpandProperties	ad specifies new expand properties	no
getMaxSize	ad request max ad container dimensions available	yes
getScreenSize	ad requests dimensions of device screen	yes
getResizeProperties	ad requests current dimensions of the ad container in its resized state	no
setResizeProperties	ad specifies dimensions for resizing the ad container	no
getLocation	ad requests current coordinates of the device	no
VPAID Methods	a collection of methods used to manage a VPAID video ad in the context of MRAID • initVpaid • vpaidObject.subscribe • vpaidObject.startAd • vpaidObject.unsubscribe • vpaidObject.getAdDuration • vpaidObject.getAdRemainingTime	No
Events
error	host reports an error	yes
ready	host reports that MRAID libraries are loaded	yes
sizeChange	host reports that ad container dimensions have changed	yes
stateChange	host reports that the state of the ad container has changed	yes
exposureChange	host reports that the percentage of ad container exposure has changed	No
audioVolumeChange	host reports a change in volume	No
viewableChange	host reports a change in ad container viewability	yes
Supports
sms	the device supports using the sms: protocol to send an SMS message	no
tel	the device supports initiating calls using the tel: protocol	no
calendar	the device can create a calendar entry	no
storePicture	the device supports the MRAID storePicture method	no
inlineVideo	the device can playback HTML5 video files using the	no
vpaid	the device ocntainer supports VPAID handshake with ad to communicate VPAID events discussed in section 9 of the spec.	no
location	the device supports access to GPS coordinates	no

7. SKAdNetwork

Tapjoy supports SKAdNetwork versions v2.0, v2.2, and v3.0.

For VAST creatives, we will load the product view if we see that there was SKAN information returned in the bid response upon any click (end card or video).

For MRAID creatives, we will override the mraid.open(url) method to open the product view with the appropriate SKAN information instead of the URL.

8. Error Tracking

Whenever an error occurs during the VAST parsing, the parser will automatically call all related tracking error URLs. Reported errors are:

• VAST error 101: VAST schema validation error.
• VAST error 301: Timeout of VAST URI provided in Wrapper element.
• VAST error 302: Wrapper limit reached.
• VAST error 303: No VAST response after one or more Wrappers.
• VAST error 405: Problem displaying MediaFile. Video player found a MediaFile with the supported type but couldn’t display it. MediaFile may include: unsupported codecs, different MIME type than MediaFile@type, unsupported delivery method, etc.

9. Change Log

• 2023-02-01 Added 200 loss reason
• 2022-04-21 Updated privacy flag descriptions and added pos parameter as a new field.
• 2021-12-17 Added banner object
• 2021-11-19 SupplyChain and Header Bidding Objects added
• 2021-09-27 Request and Response fields, creative requirements, and skadnetwork
• 2021-09-13 Initial Release to outline lurl specification