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:
separate multiple values by a comma (e. g. |
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.
Calling specific VAST ad versions:
|
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 In case of multiple keywords or key=values, use a semicolon (;) to separate them (e.g. 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 |
parameter is optional; if absent, the default value is used: |
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:
default value: |
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
ⓘ 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.
|
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;
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:
|
vpaidt | STRING | OPTIONAL | the VPAID type; vpaidt=js requests the VPAID type "javascript" |
vpaidv | INTEGER | OPTIONAL |
the VPAID version:
|
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
|
vpmt | INTEGER | OPTIONAL |
the video playback method; set to -1 by default (feature disabled):
|
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
|
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.