For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

Response

The response is made in JSON format.


Response Parameters

Type

In the response, the type field sets what ad format is being used. It can be any one of the following:

  • banner

  • sticky_banner

  • popunder

  • instant_message

  • mobile_instant_message

  • native_ad

  • outstream_video

  • desktop_fullpage_interstitial

  • mobile_fullpage_interstitial

  • push_notification

  • in_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.

Zones

Parameter
Description

idzone

The ID of the ad zone

type

The ad format used, e.g. banner

Data

Parameter
Description

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

Image Banner

HTML Banner

Video Banner

Sticky Banner

Zones

Parameter
Description

idzone

The ID of the ad zone

type

The ad format used, e.g. sticky_banner

Data

Parameter
Description

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

Parameter
Description

idzone

The ID of the ad zone

type

The ad format used, e.g. popunder

Data

Parameter
Description

url

The URL that the ad directs to

Popunder Response Example: JSON

Instant Message

Zones

Parameter
Description

idzone

The ID of the ad zone

type

The ad format used, e.g. instant_message

Data

Parameter
Description

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

Parameter
Description

idzone

The ID of the ad zone

type

The ad format used, e.g. mobile_instant_message

Data

Parameter
Description

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

Parameter
Description

idzone

The ID of the ad zone

type

The ad format used, e.g. native_ad

Data > Layout

Parameter
Description

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

Parameter
Description

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

Parameter
Description

idzone

The ID of the ad zone

type

The ad format used, e.g. outstream_video

Data

Parameter
Description

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

Parameter
Description

idzone

The ID of the ad zone

type

The ad format used, e.g. desktop_fullpage_interstitial

Data

Parameter
Description

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

Parameter
Description

idzone

The ID of the ad zone

type

The ad format used, e.g. mobile_fullpage_interstitial

Data

Parameter
Description

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

Parameter
Description

idzone

The ID of the ad zone

type

The ad format used, e.g. in_page_push_notification

Data

Parameter
Description

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

Parameter
Description

idzone

The ID of the ad zone

type

The ad format used, e.g. push_notification

Data

Parameter
Description

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:

If the creative is 720x480, the payload also includes options.image with the larger image. An empty response body means there is no notification to deliver.

Last updated

Was this helpful?