OpenWrap Ad Unit Configuration

OpenWrap now supports ad unit configuration for profiles using mobile in-app, display (including native), and video platforms. Ad unit configuration applies across all bidders. Use this guide to learn to:

  • Upload new ad unit configurations.
  • Download existing configurations.
  • Delete existing configurations.

Upload an ad unit configuration

  • Ad units can only be configured when the version is in draft status.
  • Each time you upload an ad unit configuration, it overwrites the previous configuration.

Follow these steps to upload an ad unit configuration.

  1. Select Inventory > OpenWrap from the main navigation screen.
  2. Select the Profile Management tab.
  3. Select your profile from the Select Profile dropdown list.
  4. Choose Actions > Map Ad Units for the most recent version.

  5. For Ad Unit Configuration (Optional), from the Actions menu > Upload Config and upload your JSON file.
  6. The following message will appear when upload is complete:


Configuration status

To view the status of the configuration (uploaded or deleted), select the version number. 

Download an ad unit configuration

The Download Config option is available only when an ad unit configuration is already uploaded. If it's not uploaded, you won't see this option.

  1. Go to  Inventory  >  OpenWrap.
  2. Select the Profile Management tab.
  3. Select your profile from the Select a Profile dropdown list.
  4. Choose Actions > Map Ad Units next to the most recent version.

  5. For Ad Unit Configuration (Optional), choose  Actions > Download Config  and the JSON config file would be downloaded.

Delete an ad unit configuration

The Delete Config option is only available when an ad unit configuration is already uploaded. If it is not uploaded, you won't see this option.

  1. Select the Profile Management tab.
  2. Select your profile from the Select Profile drop-down list.
  3. Choose Actions > Map Ad Units next to the most recent version

  4. For Ad Unit Configuration (Optional), choose  Actions > Delete Config  and the JSON config file would be downloaded.
     
  5. The following message will appear when the configuration has been deleted:

You can download deleted ad unit configurations by choosing Actions > Download Config.

Sample JSON and guidelines

If your configuration is intended to work with OpenWrap SDK…

OpenWrap SDK ignores the minduration attribute used in the sample below.


Sample ad unit configuration JSON
{
  "configPattern": "_AU_",
  "config": {
    "default": {
      "video": {
        "enabled": true,
        "config": {
          "skipafter": 5,
          "maxduration": 60,
          "skip": 1,
          "skipmin": 5,
          "minduration": 5,
          "playbackmethod": [
            1,
            2
          ],
          "clientconfig": {
            "timeouts": {
              "wrapperTagURI": 8000,
              "mediaFileURI": 9000
            }
          }
        }
      },
      "banner": {
        "enabled": true,
        "config": {
          "clientconfig": {
            "refreshinterval": 30
          }
        }
      }
    },
    "Slot1": {
      "banner": {
        "enabled": true,
        "config": {
          "clientconfig": {
            "refreshinterval": 60
          }
        }
      },
      "video": {
        "enabled": true,
        "config": {
          "minduration": 10,
          "maxduration": 60,
          "skip": 1,
          "skipmin": 10,
          "skipafter": 10,
          "playbackmethod": [
            5,
            6
          ],
          "clientconfig": {
            "reward": {
              "rewards": [
                {
                  "type": "coins",
                  "value": 10
                },
                {
                  "type": "lives",
                  "value": 2
                }
              ]
            },
            "timeouts": {
              "wrapperTagURI": 11000,
              "mediaFileURI": 12000
            }
          }
        }
      }
    }
  }
} 

Media types in configuration JSON

You can specify configuration parameters for the following media types at an ad slot level or a default level: video, banner and native. Here are some important notes about the configuration JSON:

  1. The "config" JSON key contains the default and slot level config values. Default level config is represented by "default" key where as each ad slot are represented by its slot name as key.
  2. The " configPattern" JSON key indicates how the slot names are defined in step #1. Possible values are listed below. Default values is "_AU_".

    configPattern valueMeaning
    "_AU_"Ad Unit value is used as slot name
    "_DIV_"Div value is used as slot name
  3. If an ad slot level configuration is unavailable, the system uses the default-level configuration.

The following table lists the supported video keys:

AttributeDescriptionData type
battrBlocked creative attributes. (Values supported by oRTB 2.5 spec should be sent.)Array of Integers
mindurationMinimum video ad duration in seconds.Integer
maxdurationMaximum video ad duration in seconds.Integer
skipDetermines whether the player allows the video to be skipped; 0 = no, 1 = yes.Integer
skipminVideos of total duration greater than this number of seconds are skippable.Integer
skipafterNumber of seconds a video must play before allowing the user to skip the video.Integer
clientconfig

Use the clientconfig object to return operational information to OpenWrap SDK by the OpenWrap S2S response:

AttributeUnitDescriptionSDK default value
refreshintervalsecondsOpenWrap SDK auto-refreshes the banner (display/video) ads after this interval.
OpenWrap SDK defaults to the ad unit level refresh value over the profile level.
When enabled, min refresh interval is 10 seconds.
The value configured in the OpenWrap profile.
timeouts:wrapperTagURImillisecondsOpenWrap SDK sends a TIMEOUT error to the app if the wrapper ad tag URI doesn't load within this time value. The SDK also sends VAST error code 301.1 second
timeouts:mediaFileURImillisecondsOpenWrap SDK sends a NETWORK error if the media file doesn't load within this time value. SDK also sends VAST error code 402.10 seconds
rewardsArray of key-value paired reward objects

List of rewards to be used if a partner bids on the rewarded ad slot:

rewards[i].type /* string: currency of the reward */
rewards[i].value /* positive integer | value of the reward */

Notes: 
1. If your app does not return a reward from the list, OpenWrap returns the first reward by default.
2. The best practice is to add the rewards in slot-level clientconfig instead of relying on the default.

In a MoPub integration, OpenWrap SDK uses MoPub's reward configuration and validation capabilities. In this case, rewards configured through OpenWrap are not valid.

N/A

To learn more about the clientconfig object see, Using the clientconfig object with video ads in OpenWrap SDK below.

JSON object
enabledIndicates whether video bidding is enabled for this ad slot, where true = yes, false = no.Boolean
connectiontype

List of network connection types appropriate for the video being served:

    0 = Unknown
   1 = Ethernet
   2 = WIFI
   3 = Cellular Network – Unknown Generation
   4 = Cellular Network – 2G
   5 = Cellular Network – 3G
   6 = Cellular Network – 4G
   7 = Cellular Network – 5G

Best practice to optimize user experience…

Avoid using video ads with a 2G connectiontype.
Array of Integers
playbackmethodArray of playback methods that may be in use (send values supported by oRTB 2.5 spec). See, Using the clientconfig object with video ads > Remote configurations for video.Array of Integers
contextRequired for Video ads using OpenWrap client-side integrations. Indicates if the ads are instream or outstream. Currently, the only acceptable value for this field is: instreamString
mimesContent MIME types supported. (Values supported by oRTB 2.5 spec should be sent.)Array of Strings
protocolsArray of supported video protocols. (Values supported by oRTB 2.5 spec should be sent.)Array of Integers
wWidth of the video player in device independent pixels (DIPS).Integer
hHeight of the video player in device independent pixels (DIPS).Integer
startdelayIndicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements.Integer
placementPlacement type for the impression.Integer
linearityIndicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed. (Values supported by oRTB 2.5 spec should be sent.)Integer
sequenceIf multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.Integer
maxextendedMaximum extended ad duration if extension is allowed. If blank or 0, extension is not allowed. If -1, extension is allowed, and there is no time limit imposed. If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxduration value.Integer
minbitrateMinimum bit rate in Kbps.Integer
maxbitrateMaximum bit rate in Kbps.Integer
boxingallowedIndicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes.Integer
deliverySupported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported. (Values supported by oRTB 2.5 spec should be sent.)Array of Integers
posAd position on screen. (Values supported by oRTB 2.5 spec should be sent.)Integer
companionadArray of Banner objects (Section 3.2.6) if companion ads are available. (See oRTB 2.5 spec for Banner object in request)Array of Banner objects
apiList of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported. (Values supported by oRTB 2.5 spec should be sent.)Array of Integers
companiontypeSupported VAST companion ad types. (Values supported by oRTB 2.5 spec should be sent.)Array of Integers
  1.  Supported banner key:

    AttributeDescriptionData type
    clientconfigEnter attributes here that you want returned in the OpenWrap S2S response.JSON object
    enabled Indicates if banner bidding is enabled for this ad slot, where true = yes and false = no.Boolean
  2. Enable/disable banner/video/native bidding:
    1. The enabled attribute defaults to true at ad slot and default levels.
    2. To disable video bidding for a profile use:
      set config.default.video.enabled = false
      To disable banner bidding for a profile use:
      set config.default.banner.enabled = false
      This overrides the ad slot level enabled setting.
    3. To disable video bidding for a particular ad slot use:
      set config.<slotname>.video.enabled = false

      To disable video bidding for a particular ad slot use:

      set config.<slotname>.banner.enabled = false
  3. As mentioned in step 2, OpenWrap uses default configuration when there is no ad slot level configuration found for a given ad slot. If configuration attributes exist at the ad slot level (for example,  video.config.minduration  and  video.config.maxduration) , OpenWrap uses those to populate banner/video/banner requests to partners, instead of other attribute values from the default configuration.

Using the clientconfig object with video ads in OpenWrap SDK

Expand the questions below to learn more about the role of the clientconfig object in OpenWrap SDK.

 How does banner auto refresh work?

Starting with OpenWrapSDK v1.7.0, you can configure the refresh interval at the:

  1. Profile Level (see, OpenWrap Mobile In-App Support).
  2. Ad Unit Level (see, OpenWrap Ad Unit Configuration).

OpenWrap SDK defaults to the ad unit level refresh interval over the profile level. OpenWrap SDK supports a minimum refresh interval of 5 seconds. If configured to 0, OpenWrap SDK doesn’t refresh the ad. For in-banner video ads, the next ad request waits until video playback completes, so ads refresh after the refresh interval or video duration, whichever is greater. For example, if the refresh interval is less than the video duration, the video duration supersedes the refresh interval and ad refreshes when the playback completes.


Clientconfig example:
"banner": {
    "config": {
      "clientconfig": {
        "refreshinterval": 30
      }
    }
  },
"video": {
    "config": {
      "clientconfig": {
        "refreshinterval": 60
      }
    }
  }

Important…

Turn off the ad server's refresh functionality if you define a Refresh Interval in your OpenWrap profile or ad unit configurations.

 What is the maximum timeout for loading/buffering a media file?

OpenWrap SDK defaults to a maximum timeout value of 10 seconds. OpenWrap SDK honors the timeout value received in the ad response if it is greater than 10 seconds. To learn about configuring the timeout value in the OpenWrap portal see, VAST bidder tag management. Add the clientconfig  attribute under the video attribute of  your ad unit configuration JSON:

Clientconfig example:
  "video": {
    "config": {
      "clientconfig": {
        "timeouts": {
          "mediaFileURI": 15000
        }
      }
    }

 What are the remote configurations applicable for video? What are the default values, if not configured at the OpenWrap portal?

The configurable properties at the OpenWrap portal are:

  • Enable/disable video mappings
  • Skip info - skip, skipmin, skipafter (applicable for interstitial video and rewarded video only).
  • Player audio settings (Mute by default):
    • For SDK v1.5.0 - video.config.playbackmethod.
  • Timeouts:
    • Media file.
    • Wrapper timeouts.

To configure these properties at the OpenWrap portal see, VAST bidder tag management. Add the clientconfig attribute under the video attribute of your ad unit configuration JSON:

Clientconfig example:
  "video": {
    "enabled": true,
    "config": {
      "minduration": 5,
      "maxduration": 30,
      "skip": 1,
      "skipmin": 5,
      "skipafter": 15,
      "playbackmethod": [
        2
      ],
      "clientconfig": {
        "timeouts": {
          "wrapperTagURI": 10000,
          "mediaFileURI": 15000
        }
      }
    }
  }

In the OpenWrap S2S response,the clientconfig object delivers information that OpenWrap SDK uses to define ad behavior. The following table lists clientconfig properties:

Property nameUnitUsageSDK default value
timeouts:wrapperTagURImillisecondsSDK sends a TIMEOUT error to the app if wrapper ad tag URI doesn't load within this time. SDK also sends VAST error code 301.1 second
timeouts:mediaFileURImillisecondsSDK sends a NETWORK error if the media file doesn't load within this time. SDK also sends VAST error code 402.10 seconds

 Do video ads play with sound? Are there any default sound settings?

Video ads play on mute and rewarded video ads play on unmute by default. You can change the default behavior by editing the video.playbackmethod attribute in your ad unit config JSON in the OpenWrap portal, as described in the oRTB standard. When:

  • video.config.playbackmethod = [2] - the video ad player mutes audio.
  • video.config.playbackmethod = [1] - audio plays according to the local device's audio settings.

Currently, SDK supports only two values for this attribute, 1 or 2. The best practice is to use only one of these values.

If you set:

  • multiple values for this parameter: OpenWrap SDK uses the first value specified to determine behavior.
  • for any unsupported value (other than 1 or 2), OpenWrap SDK defaults to 2; that is, the video player mutes audio.

Sample ad unit configuration JSON

The OpenWrap profiles created for native ads using OpenWrap release version prior to v18.5.0 do not support the above ad unit configuration JSON format. Here is a sample of the format for native configuration JSON prior to OpenWrap v18.5.0:

Native configuration JSON
{
    kgp:"_DIV_",
    klm:{
        "DIV1":{
            "nativeOnly": true, 
            config: {
                image: {
                    required: true,
                    sizes: [150, 50]
                },
                title: {
                    required: true,
                    len: 80
                },
                sponsoredBy: {
                    required: true
                },
                body: {
                    required: true
                }
            }
        },
        "DIV2":{
            config: {
                image: {
                    required: true,
                    sizes: [150, 50]
                },
                title: {
                    required: true,
                    len: 80
                },
                sponsoredBy: 
                    required: true
                },
                body: {
                    required: true
                }
            }
        }
    }
}

For more details on this configuration JSON and on Native ads support in OpenWrap; see, OpenWrap Native Ad Support.

⇧ Top

Do you have feedback on this document? Let us know: email us.

Table of Contents