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

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

  • 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