Contact support

GET Ad API integration

Overview

This article describes Equativ’s GET Ad API, which is based on the HTTP GET method, mainly used for in-stream video and in Connected TV environments. Note that the HTTP POST method is the preferred method for any HTTP POST compatible integration. See POST Ad API integration: usage and POST Ad API integration: parameter reference for more details. 

 

Equativ's ad API allows you to request and retrieve web, in-app, and video ads from Equativ. It can be used in the following scenarios:

  • server-side applications requesting ads from Equativ
  • in-app implementations without Equativ's in-app display SDK (NB: Equativ’s SDK is strongly recommended for convenience and full feature support)
  • any other environment (desktop, mobile web etc.) where client-side ad tags are not used (for more about ad tags, see Tagging guide: get started.  

GET ad request syntax

A GET ad request has the following syntax:

http://[subDomain].smartadserver.com/ac?siteid=[siteId]&pgid=[pageId]&fmtid=[formatId]&visit=M&tmstp=[timestamp]&tgt=[target]&out=[outputType]
  • [subDomain] - the ad request domain that the given network is running on; one way to determine the domain is to:
    • sign in to Monetization
    • go to Administration > Websites & pages
    • select any page in the left pane
    • under Tags, expand the Generic function and check the sas.setup method; example: sas.setup({ networkid: 73, domain: "https://diff.smartadserver.com", async: true })
  • parameters are specified in key=value format (e. g.: siteid=20697) and separated by an ampersand ("&")
  • placeholders (e. g. [siteId]) must be replaced by the actual value

Headers

X-Forwarded-For header

The http header X-Forwarded-For is optional but strongly recommended — in particular in integrations where Equativ is being called server-side. In such server-side contexts, the proper setup of the X-Forwarded-For header ensures that Equativ gets the IP address of the end user, and not the IP of the server that is calling Equativ. Sending multiple IPs in the X-Forwarded-For header (separated by comma) is possible but not recommended. If multiple IPs are sent, Equativ will consider the first (left most) IP address as the IP of the original client.  

An error in the configuration of the “X-Forwarded-For” header can lead to a serious drop in revenue: for instance, the monetization may be stopped because the network is classified as invalid traffic; or a buyer may block some inventory since the erroneous IP address is seen as potentially malicious.

 

User agent

The user agent must be specified using the HTTP header User-Agent.

In case of mobile in-app calls, using the User-Agent of the native browser of the device is strongly recommended. In case of iOS, this would be the User-Agent from a UIWebView or WKWebView. If the User-Agent differs too much from the native one, some targeting options may stop working. 

General parameters

The general parameters apply to all types of ads: web, in-app, and video ads. Specific parameters that apply to in-app / video ads only, are listed in chapters "In-app parameters" and "Video parameters" below.

Key Type Necessity Description
Placement related parameters
fmtid INTEGER REQUIRED the format ID; represents an ad slot on a page or in an app (e. g. medium rectangle); read more about formats in Create placements
pgid INTEGER REQUIRED the page ID; child element of a website; represents a category/section on a website, in an app or in a video player; read more about pages in Create placements
pgname STRING OPTIONAL the page name; usage not recommended; can be used instead of pgid to identify the page; required if pgid is not provided; if pgname is used, siteid is required as well; usage available upon request only - please contact Equativ support
siteid INTEGER OPTIONAL the site ID; represents a website, mobile application or a video player; read more about sites in Create placements
Other parameters
ckid STRING OPTIONAL Equativ’s proprietary user identifier; used to ensure appropriate user synching with partners; optional but strongly recommended in case of Ad API integrations where there is no way to access cookies in users' browsers
clcturl STRING OPTIONAL the encoded click tracking URL of a third party system, used to build the final click tracking URL, so both systems can count the click. In the special case of a VAST creative in a direct insertion, the third party click tracking URL is not part of the final click URL redirection chain.
eids STRING OPTIONAL the Base64 encoded extended ID payload, as specified by the IAB openRTB specs
gdpr BOOLEAN OPTIONAL indicates if the given request is from a location where the GDPR applies; if not provided, Equativ will attempt to leverage the geolocation of the user to determine if the GDPR applies; "0" if the GDPR does not apply; "1" if the GDPR applies; more details about GDPR in Comply with Global Privacy Platform (GPP)
gdpr_consent STRING REQUIRED (for EU traffic) the encoded GDPR consent string, as defined by the IAB Transparency & Consent Framework. ⓘ Note: if the gdpr parameter is set to "1", gdpr_consent becomes mandatory; more details about GDPR in Comply with Global Privacy Platform (GPP)
gpp STRING OPTIONAL the Global Privacy Platform (GPP) consent string
gpp_sid STRING OPTIONAL an array of the section(s) of the GPP string to be applied for this transaction; generally, will contain one and only one value; more than one may apply in rare cases; see list of section IDs
iabframeworks STRING OPTIONAL

the supported IAB API frameworks for the given impression:

  • 1 - VPAID 1.0
  • 2 - VPAID 2.0
  • 3 - MRAID-1
  • 4 - ORMMA
  • 5 - MRAID-2
  • 6 - MRAID-3
  • 7 -  OMSDK

separate multiple values by a comma (e. g. iabframeworks=1,2,7

ip STRING OPTIONAL IP address of the end user. This parameter is useful when the IP address cannot be passed in the HTTP header of the request. In case the IP address is passed with multiple methods, then the priority applied is: IP parameter in the URL > IP address in x-forwarded-for header > actual IP address from the HTTP request
jump INTEGER OPTIONAL used in nonrich calls (see out=nonrich below): the click URL (href) must include jump=1
la DOUBLE OPTIONAL the latitude of the device
lg DOUBLE OPTIONAL the longitude of the device
omidpn STRING REQUIRED (if iabframeworks=7 is sent) “Open Measurement Interface Definition partner name”; specifies the identifier of the OM SDK integration; this is the same as the name parameter of the OMID Partner object; see also Open Measurement SDK - Onboarding Guide for Integration Partners (p. 27); Equativ sends omidpn in the bid request only if iabframeworks=7 is sent in the ad request
omidpv STRING OPTIONAL “Open Measurement Interface Definition partner version”; specifies the version of the OM SDK integration; this is the same as the versionString parameter of the OMID Partner object; see also Open Measurement SDK - Onboarding Guide for Integration Partners (p. 27); Equativ sends omidpv in the bid request only if iabframeworks=7 is sent in the ad request; omidpv cannot be sent without any omidpn value
out STRING OPTIONAL

requests a specific type of response; 

mandatory for video ad requests; if missing, Equativ will return the default ad response which is based on the placement setup in Equativ's system (format type: Web, App (SDK) or Video); see also Create placements 

values can be either literal (e. g. out=js) or value (e. g. out=1) :

  • Javascript: out=js or out=1 
  • Nonrich: out=nonrich or out=2
  • Iframe: out=iframe or out=4
  • XML: out=xml or out=8
  • JSON: out=json or out=16
  • VAST: out=vast or out=32 (calls a VAST ad with version 4.0 or lower; read about calling specific VAST ad versions below)

Calling specific VAST ad versions:

  • out=vast4.2 - calls a VAST ad with version 4.2 or lower
  • out=vast4.1 - calls a VAST ad with version 4.1 or lower
  • out=vast4 or out=vast or out=32 - calls a VAST ad with version 4.0 or lower
  • out=vast3 - calls a VAST ad with version 3.0 or lower
  • out=vast2 - calls a VAST ad with version 2.0
schain STRING OPTIONAL the SupplyChain Object parameter; lists all parties who are selling or reselling the ad; each party is represented by a SupplyChain Object node; e.g.: "1.0,1!exchange1.com,1234,1,publisher,publisher.com"
tgt STRING OPTIONAL

the key=value targeting of the ad (e.g: gender=male); 

In case of multiple keywords or key=values, use a semicolon (;) to separate them (e.g. color=green;color=red;sport;football). 

The comma character (,) must never be used as a separator because this character will be considered as part of the key=value or keyword itself. 

Read more in Set keyword targeting.

tmax INTEGER OPTIONAL imposes a timeout on Equativ in milliseconds; does not take into account any latency between publisher and Equativ; therefore, it is advised to use a little more restrictive timeout; accepted values: > 0; any value < 0 will be changed to 0
tmstp LONG REQUIRED a timestamp to be generated; a random number, mainly used for cache busting purposes
visit STRING OPTIONAL
  • m - master request; indicates that the request should be counted as a page impression; use m only for the first request from a given page; all subsequent requests from the same page should use s
  • s - slave request; indicates that the request should be counted as a regular ad impression; do not use s for the first request from a given page;

parameter is optional; if absent, the default value is used: m (master) in case of OneCall or s (slave) in case of standard call

In-app parameters

Key Type Necessity Description
appname STRING REQUIRED the application name (URL-encoded)
buid STRING OPTIONAL the application bundle ID; has the form of a right-to-left domain name, e. g. com.my-app-name;
ifa STRING OPTIONAL The identifier for advertising of the device. If not present, Equativ will fall back on the uid parameter.
mraid STRING OPTIONAL the MRAID version; allowed values: 1.x.x or 2.x.x only the major version number will be taken into consideration; at least one minor version number is mandatory! e. g.: 1.6 or 2.4 are allowed but 1 or 2 are not allowed
uid STRING OPTIONAL a unique identifier for the user that can be used instead of Equativ’s pid; used for mobile devices (IDFA for iOS, Advertising ID for Android)

Video parameters

Key Type Necessity Description
ab INTEGER REQUIRED

the ad break; possible values:

  • 0 - default
  • 1 - preroll
  • 2 - midroll
  • 3 - postroll
  • Not set for overlays

default value: 1

config STRING OPTIONAL the (encoded) URL of a JSON configuration file to be used by the Equativ Video Plugin; see Ad Plugin Configuration
ctc STRING OPTIONAL the video content category; supports one or multiple values; multiple values must be separated by a comma – e. g.: ctc=cat1,cat2,cat3; Key name in Video plugin*: sas_videoContentCategory; Macro name: [sas_videoContentCategory]
ctch STRING OPTIONAL the name of the content channel; Key name in Video plugin*: sas_videoContentChannelName 
ctd STRING OPTIONAL the video content duration in seconds; the value -1 indicates a live stream; Key name in Video plugin*: sas_videoContentDuration; Macro name: [sas_videoContentDuration]
ctdid STRING OPTIONAL the video content distributor Id; Key name in Video plugin*: sas_videoContentDistributorId; Macro name: [sas_videoContentDistributorId]
ctdn STRING OPTIONAL the video content distributor name; Key name in Video plugin*: sas_videoContentDistributorName; Macro name: [sas_videoContentDistributorName]
cte STRING OPTIONAL the episode number of the content; format ISO-639-1-Alpha-2 is strongly recommended; Key name in Video plugin*: sas_videoEpisodeNumber; Macro name: [sas_videoEpisodeNumber]
ctgr STRING OPTIONAL the genre describing the content (e. g. "Rock", "Pop")
ctid STRING OPTIONAL the video content Id to uniquely identify the content; used for syndication purposes; Key name in Video plugin*: sas_contentid; Macro name: [sas_contentid]
ctk STRING OPTIONAL one or multiple keywords (tags) that describe the video content (separated by comma); Key name in Video plugin*: sas_videoContentTags; Macro name: [sas_videoContentTags]
ctlg STRING OPTIONAL the language of the content; format ISO-639-1-Alpha-2 is strongly recommended
ctmsid STRING OPTIONAL the content management system Id in charge of the video content; Key name in Video plugin*: sas_videoCmsId; Macro name: [sas_videoCmsId]
ctn STRING OPTIONAL the video content name (title); Key name in Video plugin*: sas_contentTitle; Macro name: [sas_contentTitle]
ctnw STRING OPTIONAL the name of the content network; Key name in Video plugin*: sas_videoContentNetworkName 
ctp STRING OPTIONAL the video content provider name; Key name in Video plugin*: sas_contentProviderName; Macro name: [sas_contentProviderName]
ctpid STRING OPTIONAL the video content provider ID; used for syndication purposes; Key name in Video plugin*: sas_contentproviderid; Macro name: [sas_contentproviderid]
ctr STRING OPTIONAL the permissible audience of the video content (general audiences, parental guidance, adult, etc.); supports one or multiple values; multiple values of a key must be separated by a comma; Key name in Video plugin*: sas_videoContentRating; Macro name: [sas_videoContentRating]
cts STRING OPTIONAL the video content season number; Key name in Video plugin*: sas_videoSeasonNumber; Macro name: [sas_videoSeasonNumber]
ctt STRING OPTIONAL the video content type; supports one or multiple values; multiple values must be separated by a comma; Key name in Video plugin*: sas_videoContentType; Macro name: [sas_videoContentType]
ctxid STRING OPTIONAL the video content id in an external (3rd party) system; Key name in Video plugin*: sas_externalContentId; Macro name: [sas_externalContentId]
enableSSAR BOOLEAN OPTIONAL

a boolean indicating of Server side Video ad rules are enabled or not.

You can also set this parameter in the optional JSON configuration file using the same syntax. If the parameter exists in both ad call and JSON configuration file, the setting in the JSON configuration file will override the setting in the ad call.

ipd STRING OPTIONAL the inventory partner domain to designate a domain of an inventory sharing partner for purposes of ads.txt/app-ads.txt validation (see "inventorypartnerdomain" in the IAB specification)
lang STRING OPTIONAL the language of the video player labels; “en” by default
live BOOLEAN OPTIONAL a boolean indicating if the ad request is originating from an ad break in a live video stream (live event) or not; live video streams generate traffic peaks during ad breaks (many simultaneous ad requests); live=1 ensures appropriate ad delivery pacing during such ad breaks; default value: 0;
mabd STRING OPTIONAL the maximum adbreak duration; sets a duration limit for the ad pod (in seconds)
maxdur INTEGER OPTIONAL the maximum duration of an ad pod (in seconds); must be a positive integer; not taken into account if undefined or if its value is 0 or a negative integer
oc INTEGER REQUIRED a boolean required to enforce the processing of the video ad request as a OneCall (oc=1); allows for the retrieval of ad responses with several ad units concatenated in a single VAST node. 
pb INTEGER OPTIONAL

the number of passback ads; defines the number of additional ads to be delivered with the VAST response for failover (fallback) purposes (see "ad buffet" in the VAST specification); 

default (if pb is not specified): 4 passback ads, if available on the placement; a maximum of 10 passback ads can be served; 

pb=0 disables passback ads entirely 

ⓘ Note: only insertions without any video ad pod position targeting can be served as passback ads; read Set video ad pod position targeting for more on video ad pod position targeting

pgDomain STRING  OPTIONAL the encoded page domain, indicating where the video ad call is originating from
ps INTEGER OPTIONAL the ad pod size; specifies the number of sequenced ads to be returned in the VAST ad response; default: ps=1; max value: 20; overrides the number of instances defined on format level (more about format instances in Create placements
skip  BOOLEAN OPTIONAL a boolean indicating in the bid request if a video ad is skippable or not
srl STRING OPTIONAL the store URL of a connected TV / mobile application; if missing in the ad request, Equativ will build and pass the store URL through an automated fallback mechanism; however, this mechanism is applied only in case the store URL is missing in the ad request (no overriding of erroneous store URLs through this mechanism!)
ssar STRING OPTIONAL

a boolean indicating of Server side Video ad rules are enabled or not.

  • ssar=0 deactivates server side ad rules and activates client side ad rules
  • ssar=1 activates server side ad rules and deactivates client side ad rules
vbrmax INTEGER OPTIONAL the maximum bitrate of the video creative served programmatically, in Kbps; must have a positive value
vbrmin INTEGER OPTIONAL the minimum bitrate of the video creative served programmatically, in Kbps; must have a positive value
vcn STRING OPTIONAL

a boolean indicating if noad is counted client-side or server-side; noad occurs when more ads are requested than available on the placement;  noad counting is done for reporting and forecasting purposes;

  • s for server-side counting (default)
  • c for client-side counting (used in case of Equativ's video plugin or Embedded Ad Manager); in case of client side counting using standalone VAST requests, noad should be counted as described in section “Counting empty inventory in case of standalone VAST requests” in Supply in-stream video inventory: get started

The server side counting method (vcn=s) means that Equativ counts empty (unmonetized) inventory server side. Empty inventory occurs when the number of ads returned by Equativ is less than the number of ads requested by the pod size (ps=) parameter or by the maximum ad break duration (mabd=) parameter in the VAST request. Empty inventory is counted with the report metric "No ad". Keep in mind: In case of client side counting, missing ads should be counted on the client side as described in “Counting empty inventory in case of standalone VAST requests” below.

vdmax INTEGER OPTIONAL the maximum duration of the video creative served programmatically, in seconds; must have a positive value; default value: 60
vdmin INTEGER OPTIONAL the minimum duration of the video creative served programmatically, in seconds; must have a positive value, greater than or equal to 1; default value: 1
verbose BOOLEAN OPTIONAL A boolean indicating if the Embedded Ad Manager and the video controller are to be served in their verbose or non-verbose versions; if the parameter is missing, the non-verbose version is served.
vex STRING OPTIONAL the declaration of the given ad request as being a Video Ad Exchange ad request; required for Equativ's Video Ad Exchange (VEX) offer; see Set up Video Ad Exchange: get started and Set up Video Ad Exchange: setup guide; any VAST XML ad response to such ad requests will be “flattened”: wrapper redirections are removed, while preserving the tracking URLs of all parties involved in the transaction; this parameter consists of the string vex only, i. e. it is a flag that does not have any value. 
vit INTEGER OPTIONAL

the video integration type passed by Equativ’s video plugin; possible values:

  • 1 - Instream Plugins
  • 2 - Instream Embedded Ad Manager
  • 3 - Outstream synchronous formats (obsolete)
  • 4 - Outstream asynchronous formats
  • 5 - Server side ad insertion (SSAI)
vpaidt STRING OPTIONAL the VPAID type; vpaidt=js requests the VPAID type "javascript"
vpaidv INTEGER OPTIONAL

the VPAID version:

  • 0 - VPAID not supported (mandatory if VPAID is not supported at all)
  • 1,2 - allows VPAID 1.0 or VPAID 2.0 creatives; default option
  • 1 - allows only VPAID 1.0 creatives
  • 2 - allows only VPAID 2.0 creatives
vph INTEGER OPTIONAL the video player height, in pixels
vplcmt INTEGER OPTIONAL

the video placement type in accordance with updated IAB Digital Video Guidelines; replaces vpt parameter; definitions below are shortened - for full definitions, see List: Plcmt Subtypes - Video

  • 1 - Instream; pre-roll, mid-roll and post-roll ads played before, during or after the streaming video content requested by user; must be sound-on by default at player start
  • 2 -  Accompanying Content; pre-roll, mid-roll and post-roll ads played before, during, or after streaming video content; video player loads and plays before, between, or after paragraphs of text or graphical content and starts playing only when it enters the viewport.
  • 3 - Interstitial; video ads played without video content; must be primary focus of the page and take up the majority of the viewport; cannot be scrolled out of view; can be placements like in-app video or slideshows.
  • 4 - No Content/Standalone; video ads played without streaming video content; can be placements like slideshows, native feeds, in-content or sticky/floating
vpmt INTEGER OPTIONAL

the video playback method; set to -1 by default (feature disabled):

  • -1: Default value, disables the feature
  • 1: Initiates on Page Load with Sound On 
  • 2: Initiates on Page Load with Sound Off by Default
  • 3: Initiates on Click with Sound On
  • 4: Initiates on Mouse-Over with Sound On
  • 5: Initiates on Entering Viewport with Sound On
  • 6: Initiates on Entering Viewport with Sound Off by Default
vpt INTEGER OPTIONAL

the video placement type; deprecated as of open RTB 2.6-202303 release; for the latest types of video placements in accordance with updated IAB Digital Video Guidelines, see vplcmt parameter above

  • 1 - In-Stream; played before, during or after the streaming video content;
  • 2 - In-Banner; exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format; the format relies on the existence of display ad inventory on the page for its delivery;
  • 3 - In-Article; loads and plays dynamically between paragraphs of editorial content;
  • 4 - In-Feed; in content, social or product feeds;
  • 5 - Interstitial / Slider / Floating; covers the entire or a portion of the screen area, but is always on screen while displayed (i.e. cannot be scrolled out of view).
vpw INTEGER OPTIONAL the video player width, in pixels

Key name in Video plugin: the key name in the contentData object when the used integration method is the Video plugin (documentation here

Ad responses

See chapter "Ad responses" in the POST Ad API integration: usage article.