Salesforce

Ad API - GET method

Printable View
« Go Back
Information
Ad API - GET method
Ad-API-GET-method-legacy
Details

In this article

Related articles
Overview
GET ad request syntax
Headers
General parameters
In-app parameters
Video parameters
Ad responses

Related articles

Overview

Important notice
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 Ad API - usage and Ad API - 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 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 Equativ’s UI
    • 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. 
Keep in mind
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____NecessityDescription
Placement related parameters
siteidINTEGEROPTIONALthe site ID; represents a website, mobile application or a video player; read more about sites in Setting up inventory
pgidINTEGERREQUIREDthe 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 Setting up inventory
pgnameSTRINGOPTIONALthe 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
fmtidINTEGERREQUIREDthe format ID; represents an ad slot on a page or in an app (e. g. medium rectangle); read more about formats in Setting up inventory
Other parameters
ckidSTRINGOPTIONALEquativ’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
clcturlSTRINGOPTIONALthe 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.
eidsSTRINGOPTIONALthe Base64 encoded extended ID payload, as specified by the IAB openRTB specs
gdprBOOLEANOPTIONALindicates 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 Global Privacy Platform (GPP)
gdpr_consentSTRINGREQUIRED (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 Global Privacy Platform (GPP)
gppSTRINGOPTIONALthe Global Privacy Platform (GPP) consent string
gpp_sidSTRINGOPTIONALan 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
iabframeworksSTRINGOPTIONALthe 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) 
ipSTRINGOPTIONALIP 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
jumpINTEGEROPTIONALused in nonrich calls (see out=nonrich below): the click URL (href) must include jump=1
laDOUBLEOPTIONALthe latitude of the device
lgDOUBLEOPTIONALthe longitude of the device
omidpnSTRINGREQUIRED (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
omidpvSTRINGOPTIONAL“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
outSTRINGOPTIONALrequests 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 Setting up inventory;
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
schainSTRINGOPTIONALthe 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"
tgtSTRINGOPTIONALthe 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 Using keyword targeting.
tmaxINTEGEROPTIONALimposes 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
tmstpLONGREQUIREDa timestamp to be generated; a random number, mainly used for cache busting purposes
visitSTRINGOPTIONAL
  • 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____NecessityDescription
appnameSTRINGREQUIREDthe application name (URL-encoded)
buidSTRINGOPTIONALthe application bundle ID; has the form of a right-to-left domain name, e. g. com.my-app-name;
ifaSTRINGOPTIONALThe identifier for advertising of the device. If not present, Equativ will fall back on the uid parameter.
mraidSTRINGOPTIONALthe 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
uidSTRINGOPTIONALa 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
abINTEGERREQUIREDthe ad break; possible values:
  • 0 - default
  • 1 - preroll
  • 2 - midroll
  • 3 - postroll
  • Not set for overlays
default value: 1
configSTRINGOPTIONALthe (encoded) URL of a JSON configuration file to be used by the Equativ Video Plugin; see Ad Plugin Configuration
ctcSTRINGOPTIONALthe 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]
ctchSTRINGOPTIONALthe name of the content channel; Key name in Video plugin*: sas_videoContentChannelName 
ctdSTRINGOPTIONALthe video content duration in seconds; the value -1 indicates a live stream; Key name in Video plugin*: sas_videoContentDuration; Macro name: [sas_videoContentDuration]
ctdidSTRINGOPTIONALthe video content distributor Id; Key name in Video plugin*: sas_videoContentDistributorId; Macro name: [sas_videoContentDistributorId]
ctdnSTRINGOPTIONALthe video content distributor name; Key name in Video plugin*: sas_videoContentDistributorName; Macro name: [sas_videoContentDistributorName]
cteSTRINGOPTIONALthe 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]
ctgrSTRINGOPTIONALthe genre describing the content (e. g. "Rock", "Pop")
ctidSTRINGOPTIONALthe video content Id to uniquely identify the content; used for syndication purposes; Key name in Video plugin*: sas_contentid; Macro name: [sas_contentid]
ctkSTRINGOPTIONALone or multiple keywords (tags) that describe the video content (separated by comma); Key name in Video plugin*: sas_videoContentTags; Macro name: [sas_videoContentTags]
ctlgSTRINGOPTIONALthe language of the content; format ISO-639-1-Alpha-2 is strongly recommended
ctmsidSTRINGOPTIONALthe content management system Id in charge of the video content; Key name in Video plugin*: sas_videoCmsId; Macro name: [sas_videoCmsId]
ctnSTRINGOPTIONALthe video content name (title); Key name in Video plugin*: sas_contentTitle; Macro name: [sas_contentTitle]
ctnwSTRINGOPTIONALthe name of the content network; Key name in Video plugin*: sas_videoContentNetworkName 
ctpSTRINGOPTIONALthe video content provider name; Key name in Video plugin*: sas_contentProviderName; Macro name: [sas_contentProviderName]
ctpidSTRINGOPTIONALthe video content provider ID; used for syndication purposes; Key name in Video plugin*: sas_contentproviderid; Macro name: [sas_contentproviderid]
ctrSTRINGOPTIONALthe 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]
ctsSTRINGOPTIONALthe video content season number; Key name in Video plugin*: sas_videoSeasonNumber; Macro name: [sas_videoSeasonNumber]
cttSTRINGOPTIONALthe 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]
ctxidSTRINGOPTIONALthe video content id in an external (3rd party) system; Key name in Video plugin*: sas_externalContentId; Macro name: [sas_externalContentId]
enableSSARBOOLEANOPTIONALa 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.
ipdSTRINGOPTIONALthe 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)
langSTRINGOPTIONALthe language of the video player labels; “en” by default
liveBOOLEANOPTIONALa 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;
mabdSTRINGOPTIONALthe maximum adbreak duration; sets a duration limit for the ad pod (in seconds)
maxdurINTEGEROPTIONALthe 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
ocINTEGERREQUIREDa 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. 
pbINTEGEROPTIONALthe 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
Keep in mind: Only insertions without any video ad pod position targeting can be served as passback ads; read here for more on video ad pod position targeting
pgDomainSTRING OPTIONALthe encoded page domain, indicating where the video ad call is originating from
psINTEGEROPTIONALthe 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 Setting up inventory)
skip BOOLEANOPTIONALa boolean indicating in the bid request if a video ad is skippable or not
srlSTRINGOPTIONALthe 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!)
ssarSTRINGOPTIONALa 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
vbrmaxINTEGEROPTIONALthe maximum bitrate of the video creative served programmatically, in Kbps; must have a positive value
vbrminINTEGEROPTIONALthe minimum bitrate of the video creative served programmatically, in Kbps; must have a positive value
vcnSTRINGOPTIONALa 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; 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.
vdmaxINTEGEROPTIONALthe maximum duration of the video creative served programmatically, in seconds; must have a positive value; default value: 60
vdminINTEGEROPTIONALthe minimum duration of the video creative served programmatically, in seconds; must have a positive value, greater than or equal to 1; default value: 1
verboseBOOLEANOPTIONALA 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.
vexSTRINGOPTIONALthe declaration of the given ad request as being a Video Ad Exchange ad request; required for Equativ's Video Ad Exchange (VEX) offer (see Video Ad Exchange (VEX) - Getting started and Video Ad Exchange (VEX) - 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. 
vitINTEGEROPTIONALthe 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)
vpaidtSTRINGOPTIONALthe VPAID type; vpaidt=js requests the VPAID type "javascript"
vpaidvINTEGEROPTIONALthe 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
vphINTEGEROPTIONALthe video player height, in pixels
vplcmtINTEGEROPTIONALthe 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
vpmtINTEGEROPTIONALthe 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
vptINTEGEROPTIONALthe 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).
vpwINTEGEROPTIONALthe 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 Ad API - usage article.
Powered by