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 blacklisting
badv We support advertiser domain based blacklisting
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
Video Impression
imp[0].video.mimes Tapjoy supports mp4, webm
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.skip Skippable video is supported
imp[0].video.maxbitrate
imp[0].video.playbackmethod 1,3 are only 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.pchain Supported
Regs
regs.coppa
regs.ext.us_privacy
reg.ext.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} The minimum bid value necessary to have won the auction. If your bid won the auction, this is the second highest bid that was not filtered (including the floor price). If your bid did not win the auction, this is the winning candidate's bid.
${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.

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 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 expand ad requests ad container expansion no
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 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

  • 2021-09-27 Request and Response fields, creative requirements, and skadnetwork
  • 2021-09-13 Initial Release to outline lurl specification