Response
Response Parameters
Type
In the response, the type field sets what ad format is being used. It can be any one of the following:
bannersticky_bannerpopunderinstant_messagemobile_instant_messagenative_adoutstream_videodesktop_fullpage_interstitialmobile_fullpage_interstitialpush_notificationin_page_push_notification
Impression Tracking
To record impressions for an ad, the response contains an impression field. This field contains a URL, unique to that ad, that records when an impression takes place.
The best way to use this impression URL is to GET it in the user's browser. One way to achieve this is to add the following to the page where the ad is displayed:
<img src="IMPRESSION_TRACKER_URL" width="0" height="0">
The IMPRESSION_TRACKER_URL is the URL returned in the impression field of the response.
Renderers
This field holds the renderers required to display ads on the webpage. Different ad formats use different types of renderers. Some formats use both a container renderer and a content renderer, while others, such as outstream video ads, solely rely on a content renderer.
For further details on how to use these renderers, please refer to the Renderers page.
Example:
Original Zone
For a Responsive Display Ad, the original zone field holds all the necessary data to display the ad correctly.
In the example below, a native ad is rendered within a sticky container on the page. The original zone corresponds to a Sticky Banner zone, and and information from both the original zone and the native ad is needed to render the ad accurately.
Banner
Zones
idzone
The ID of the ad zone
type
The ad format used, e.g. banner
Data
url
The URL that the ad directs to
impression
The URL of the impression tracker
image
The original image uploaded for the ad
width
The width of the ad in pixels
height
The height of the ad in pixels
optimum_image
In an image banner, if the creative uploaded is an animated GIF, this is the optimized MP4 version of it that is created for use in the ad
media
This shows which type of banner this is: Image, HTML, or video: This should be img_banner, html_banner, or video_banner respectively
variation_fields
Contains the information of the customizable fields. tag: Field Identifier; value: Value associated with the field that will be displayed
count_only_viewed_impressions
Whether the zone counts only viewed impressions: 1 means the impression URL should be called only once the ad is in view (the content renderers do this automatically), 0 means the impression is counted when the ad is rendered
Banner Response Examples: JSON
Image Banner
HTML Banner
Video Banner
Sticky Banner
Zones
idzone
The ID of the ad zone
type
The ad format used, e.g. sticky_banner
Data
url
The URL that the ad directs to
impression
The URL of the impression tracker
image
The original image uploaded for the ad
optimum_image
In a sticky banner, if the creative uploaded is an animated GIF, this is the optimized MP4 version of it that is created for use in the ad
width
The width of the ad in pixels
height
The height of the ad in pixels
frequency_period
How often in minutes the ad shows
v_pos
The vertical position of the ad
h_pos
The horizontal position of the ad
media
This shows which type of banner this is: Image, HTML, or video: This should be img_banner, html_banner, or video_banner respectively
count_only_viewed_impressions
Whether the zone counts only viewed impressions: 1 means the impression URL should be called only once the ad is in view (the content renderers do this automatically), 0 means the impression is counted when the ad is rendered
Sticky Banner Response Example: JSON
Popunder
Zones
idzone
The ID of the ad zone
type
The ad format used, e.g. popunder
Data
url
The URL that the ad directs to
Popunder Response Example: JSON
Instant Message
Zones
idzone
The ID of the ad zone
type
The ad format used, e.g. instant_message
Data
url
The URL that the ad directs to
impression
The URL of the impression tracker
image
The URL of the image
optimum_image
If the creative uploaded is an animated GIF, this is the optimized MP4 version of it that is created for use in the ad
width
The width of the ad in pixels
height
The height of the ad in pixels
frequency_period
How often the ad shows in minutes
media
This shows which type of banner is used: Image, HTML, or video: This should be img_banner, html_banner, or video_banner respectively
count_only_viewed_impressions
Whether the zone counts only viewed impressions: 1 means the impression URL should be called only once the ad is in view (the content renderers do this automatically), 0 means the impression is counted when the ad is rendered
Instant Message Response Example: JSON
Mobile Instant Message
Zones
idzone
The ID of the ad zone
type
The ad format used, e.g. mobile_instant_message
Data
url
The URL that the ad directs to
impression
The URL of the impression tracker
image
The original image uploaded for the ad
optimum_image
If the creative uploaded is an animated GIF, this is the optimized MP4 version of it that is created for use in the ad
width
The width of the ad in pixels
height
The height of the ad in pixels
frequency_period
The period for frequency capping in minutes
capping
How many times the ad shows during the frequency_period
media
This shows which type of banner is used: Image, HTML, or video: This should be img_banner, html_banner, or video_banner respectively
count_only_viewed_impressions
Whether the zone counts only viewed impressions: 1 means the impression URL should be called only once the ad is in view (the content renderers do this automatically), 0 means the impression is counted when the ad is rendered
Mobile Instant Message Response Example: JSON
Native Ads
Zones
idzone
The ID of the ad zone
type
The ad format used, e.g. native_ad
Data > Layout
widgetHeaderContentHtml
The URL of the 'Powered by' branding that shows
branding_logo
The URL for the branding logo that shows if enabled
branding_logo_hover
The URL for the branding logo that shows when the user hovers over it
itemsPerRow
The number of ads that show in each row of the widget
itemsPerCol
The number of ads that show in each column of the widget
font_family
The family of font used in the ad
header_font_size
The size of font used in the branding header
header_font_color
The colour of font used in the branding header
widget_background_color
The hex code of the background colour used for the widget
widget_width
The width of the entire widget
minimum_width_for_full_sized_layout
The minimum width for a full-sized layout in pixels
item_height
The height of each individual ad
item_padding
The padding between each of the ads
image_height
The height of the image in each ad
image_width
The width of the image in each ad
text_margin_top
The size in pixels of the top text margin
text_margin_bottom
The size in pixels of the bottom text margin
text_margin_left
The size in pixels of the left text margin
text_margin_right
The size in pixels of the right text margin
title_font_size
The font size of the title for each ad
title_font_color
The font colour of the title for each ad
title_font_weight
The font weight of the title for each ad
title_decoration
Whether the title is underlined or not
title_hover_color
The font colour when the title is hovered over
title_hover_font_weight
The font weight when the title is hovered over
title_hover_decoration
Whether the title is underlined on hover or not
description_font_size
The font size of the description for each ad
description_font_color
The font colour of the description for each ad
description_font_weight
The font weight of the description for each ad
description_decoration
Whether the description is underlined or not
description_hover_color
The font colour when the description is hovered over
description_hover_font_weight
The font weight when the description is hovered over
description_hover_decoration
Whether the description is underlined on hover or not
open_in_new_window
Whether the ad should be opened in a new window when clicked. 1=yes, 0=no
mobile_responsive_type
The type of responsiveness when using a mobile device (i.e none or compact). 1=compact, 0=no
header_is_on_top
Whether the branding should be displayed above or below the ads. 1=yes, 0=no
header_text_align
The horizontal alignment of the branding header
title_enabled
Whether the title is enabled or not. 1=yes, 0=no
description_enabled
Whether the description is enabled or not. 1=yes, 0=no
image_border_size
The size in pixels of the image border
image_border_color
The hex code colour of the image border
text_align
The alignment of the text: left, center, or right
customcss_enabled
Whether custom css is enabled or not. 1=yes, 0=no
customcss
If enabled the custom css will display here
header_enabled
Whether header is enabled or not. 1=yes, 0=no
mobile_breakpoint
The breakpoint in pixels, between desktop and mobile views of the ad zone
spacing_v
The vertical spacing in pixels between the ads, set in Advanced Options
spacing_h
The horizontal spacing in pixels between the ads, set in Advanced Options
zoom
Whether the ad should zoom in/out on hover
mobile_rows
The number of rows of ads in the mobile widget
mobile_cols
The number of columns of ads in the mobile widget
use_v2_script
Whether the ad zone was created with the newer V2 setup or the older v1
text_enabled
Whether the text title and description should be displayed. 1=yes, 0=no
mobile_image_width
The width of the image in each ad on mobile
mobile_text_box_size
The text box size when on mobile. Valid range 50-500
mobile_text_enabled
Whether the title is enabled or not on mobile. 1=yes, 0=no
mobile_text_position
The position of the text on mobile: bottom or right
item_spacing_on_each_side
The padding on each side of the ads, if they were set up using the old v1 setup
text_position
Whether the text is positioned on the left or right side
text_box_size
The size of the text box in pixels. Range 50-500
widget_height
The height of the entire widget
brand_enabled
Whether the branding is enabled or not
brand_font_size
The font size of the branding
brand_font_color
The font colour of the branding
brand_font_weight
The font weight of the branding
brand_decoration
Whether the font is underlined or not
mobile_image_height
The height of the image in each ad on mobile
publisherAdType
What type of native ad this is, i.e recommendation, exit, or interstitial: native-recommendation, native-exit, native-interstitial
Data > ad_items
idvariation
The ID of the variation
image
The original image uploaded for the ad
url
The URL that the ad directs to
optimum_image
Optimized version of the uploaded creative, generated for use in ads
impression
The URL of the impression tracker
title
The title text of the ad
description
The description text of the ad
brand
The brand text of the ad
original_url
The original url of the landing page
image_position
The position of the ad image (how the image will be cropped)
size
The size of the ad format selected
iframe_url
If an iframe is used as a variation, this will be the URL of the iframe
video_thumb_id
The identifier of the video thumb asset (if present) associated with the ad creative
video_thumb_url
The URL of the video thumb asset (if present)
video_thumb_enabled
The status of the video thumb asset (if present)
count_only_viewed_impressions
Whether the zone counts only viewed impressions: 1 means the impression URL should be called only once the ad is in view (the content renderers do this automatically), 0 means the impression is counted when the ad is rendered
Native Ads Response Example: JSON
Outstream Video
Zones
idzone
The ID of the ad zone
type
The ad format used, e.g. outstream_video
Data
url
The URL that the ad directs to
impression
The URL of the impression tracker
tracking
An object with tracking info
- offset
Progress marker to persist the video view
- url
URL to call to persist the video view
video
The video ad file to load
brandingEnabled
Flag to enable the branding
frequencyPeriod
How often in minutes the ad shows
maximumWidth
Video width size
impression
The URL of the impression tracker
Outstream Video Response Example: JSON
Desktop Fullpage Interstitial
Zones
idzone
The ID of the ad zone
type
The ad format used, e.g. desktop_fullpage_interstitial
Data
url
The URL that the ad directs to
impression
The URL of the impression tracker
image
The URL of the image
optimum_image
If the creative uploaded is an animated GIF, this is the optimized MP4 version of it that is created for use in the ad
width
The width of the ad in pixels
height
The height of the ad in pixels
frequency_count
Number of times the ad will be displayed within the selected frequency period
frequency_period
The time, in minutes, during which we monitor the number of times the ad has been displayed
frequency_trigger_type
Indicates the frequency trigger type: 0 for time and 1 for the number of clicks on links within the website
ad_trigger_method
Indicates the ad trigger method: 2 to trigger on links with specific classes or 3 to trigger on any link
ad_trigger_classes
Link classes that trigger the ad, seperated by commas
first_trigger_clicks
Number of clicks required to trigger the ad when using the click frequency trigger type
next_trigger_clicks
Number of clicks required after the first trigger to activate the ad when using the click frequency trigger type
chrome_enabled
Browser compatibility: 0 indicates non-Chrome browsers, 1 encompasses all browsers, and 2 represents Chrome-only
media
Media type of the ad: img_banner for images, video_banner for video, iframe_link for iframes
capping_enabled
Whether frequency capping is enabled for the zone: 1 means frequency_count and frequency_period are applied, 0 means the ad is shown without capping
count_only_viewed_impressions
Whether the zone counts only viewed impressions: 1 means the impression URL should be called only once the ad is in view (the content renderers do this automatically), 0 means the impression is counted when the ad is rendered
Desktop Fullpage Interstitial Response Example: JSON
Mobile Fullpage Interstitial
Zones
idzone
The ID of the ad zone
type
The ad format used, e.g. mobile_fullpage_interstitial
Data
url
The URL that the ad directs to
impression
The URL of the impression tracker
image
The URL of the image
optimum_image
If the creative uploaded is an animated GIF, this is the optimized MP4 version of it that is created for use in the ad
width
The width of the ad in pixels
height
The height of the ad in pixels
frequency_count
Number of times the ad will be displayed within the selected frequency period
frequency_period
The time, in minutes, during which we monitor the number of times the ad has been displayed
frequency_trigger_type
Indicates the frequency trigger type: 0 for time and 1 for the number of clicks on links within the website
ad_trigger_method
Indicates the ad trigger method: 2 to trigger on links with specific classes or 3 to trigger on any link
ad_trigger_classes
Link classes that trigger the ad, seperated by commas
first_trigger_clicks
Number of clicks required to trigger the ad when using the click frequency trigger type
next_trigger_clicks
Number of clicks required after the first trigger to activate the ad when using the click frequency trigger type
chrome_enabled
Browser compatibility: 0 indicates non-Chrome browsers, 1 encompasses all browsers, and 2 represents Chrome-only
media
Media type of the ad: img_banner for images, video_banner for video, iframe_link for iframes
capping_enabled
Whether frequency capping is enabled for the zone: 1 means frequency_count and frequency_period are applied, 0 means the ad is shown without capping
count_only_viewed_impressions
Whether the zone counts only viewed impressions: 1 means the impression URL should be called only once the ad is in view (the content renderers do this automatically), 0 means the impression is counted when the ad is rendered
Mobile Fullpage Interstitial Response Example: JSON
In-Page Push Notification
Zones
idzone
The ID of the ad zone
type
The ad format used, e.g. in_page_push_notification
Data
url
The URL that the ad directs to
impression
The URL of the impression tracker
image
The URL of the image
optimum_image
Optimized version of the uploaded creative, generated for use in ads (null when not available)
title
The title text of the notification
description
The description text of the notification
horizontal_position
The horizontal position on the page: left, center or right
vertical_position
The vertical position on the page: top, middle or bottom
delay
Number of seconds before the notification appears after the page loads
max_notifications_on_page
Number of notifications that can appear on the page at the same time
once_closed_hide_for
Length of time in seconds that the ad is hidden for once it is closed
user_session_capping
Number of times the ad is shown to the user
delay_between_notifications
Number of seconds before the next notification appears after the previous one loads
In-Page Push Notification Response Example: JSON
Web Push Notification
A Web Push Notification zone is the one format where api.php does not return a creative. The response carries the zone's subscription prompt ("soft ask") settings; the notifications themselves are delivered later by the browser after the user subscribes.
Zones
idzone
The ID of the ad zone
type
The ad format used, e.g. push_notification
Data
soft_ask
1 shows the network's soft-ask prompt before the browser's native permission dialog; 0 goes straight to the native dialog (self-hosted zones only).
soft_ask_delay
Seconds to wait before showing the prompt. Defaults to 5 when not set.
soft_ask_horizontal_position
left, center or right. Empty means center.
soft_ask_vertical_position
top, center or bottom. Empty means center.
soft_ask_title_enabled
0 hides the prompt title.
soft_ask_title
Prompt title. Empty falls back to the renderer's localized default.
soft_ask_description
Prompt description. Empty falls back to the localized default.
soft_ask_button_yes
Accept button label. Empty falls back to the localized default.
soft_ask_button_no
Decline button label. Empty falls back to the localized default.
is_self_hosted
1 subscribes the user on the publisher's own domain through a service worker; 0 uses the network's subscription domain in a popup.
Web Push Notification Response Example: JSON
Notification Response
Once the user is subscribed, the service worker fetches each notification from v1/wpn.php and receives the notification payload:
Last updated
Was this helpful?

