Ad call parameters

Overview

This article describes the parameters passed in ad calls. The parameters carry information about the placement (site, page, format) as well as other criteria necessary to retrieve the appropriate ad. The parameters are listed by context of usage: Publisher solution, Agency solution and Video solution.

Syntax

Here is an example of an ad call; parameters after the question mark ("?"):

http://diff.smartadserver.com/ac?out=js&nwid=73&siteid=20697&pgname=mypage_1&fmtid=9689&tgt=[sas_target]&visit=m&tmstp=[timestamp]&clcturl=[countgo]
  • parameters are specified in the format key=value (e. g.: siteId=20697, where the key is siteId and the value is 20697)
  • parameters must be URL encoded
  • each key=value pair (e. g. siteId=20697) is separated by an ampersand ("&")
  • parameters must be specified in the query string (following "?"); the position (order) within the query string has no impact - you are free to change it;

Parameters - Publisher solution

This list includes the parameters used in Smart AdServer's Publisher solution. For more about the actual tagging methods, read the Tagging guide here, which includes use cases and ad tag examples.

 

Site id

  • key name: siteId
  • data type: integer
  • identifies a (responsive) website/mobile app
  • mandatory if pgname is used instead of pgid (see below)

 

Page id

  • key name: pgid
  • data type: integer
  • identifies a page under a (responsive) website or mobile app
  • mandatory if pgname is not provided; mandatory if insid is provided (see below)

 

Page name

  • key name: pgname
  • data type: string
  • identifies a page under a (responsive) website or mobile app;
    pgname can be used instead of pgid; this features may not be active in your network (get back to your support contact to have it enabled)
  • cannot be used in combination with insid (see below)
  • mandatory if page id is not provided

 

Format id

  • key name: fmtid
  • data type: integer/string
  • can have one or multiple values; multiple values must be separated by commas (,); specifying multiple integer values leads to processing as a OneCall; if parsing of one format id fails, the call returns an error
  • mandatory

 

Visit

  • key name: visit
  • data type: char
  • possible values: m or s
  • used to count page impressions; m (master) must be used for the first call on the page; s (slave) for each following call on the same page
  • mandatory

 

Targeting

  • key name: tgt
  • data type: string
  • used to pass targeting criteria; the targeting criteria string must be in key=value format (e. g. color=red), separated by semicolon (e. g. color=red;name=bob)
  • not mandatory

 

Timestamp

  • key name: tmstp or timestamp
  • data type: numeric
  • a timestamp (unique number) used for cache busting; generated with javascript or generated by multiplying a value between 0 and 1 with 10^10
  • not mandatory

 

Output

  • key name: out
  • data type: value (e. g. out=1) or string (e. g. out=js)
  • specifies the expected output (ad response)
  • possible values: 1 or js; 2 or nonrich; 4 or iframe; 8 or xml; 16 or json
  • mandatory only for video ad calls (see below: Parameters - Video solution)

 

Unique id

  • key name: uid
  • data type: string
  • identifies a mobile device (user); can also be used in any other case where cookies cannot be used for tracking the user/device.
  • not mandatory

 

OneCall

  • key name: oc
  • data type: integer
  • oc=1 is used to force processing as a OneCall; used when a single format has multiple instances (read about format instances here); oc=1 is not necessary if multiple format ids are passed
  • mandatory for video ad calls

 

Jump call

  • key name: jump
  • data type: integer
  • used for nonrich (non-javascript) calls; the click URL (href) must include jump=1
  • not mandatory

 

Fallback call

  • key name: fallback
  • data type: integer
  • fallback=1 indicates if the call comes from a template which can create a fallback call. If specified, the selected insertion is guaranteed to not be involved in a link or an exclusion group
  • not mandatory

 

Insertion id

  • key name: insid
  • data type: integer
  • used for a direct call to receive the specified insertion id;
    if specified, any ad selection criteria (e. g. priority, capping, targeting etc.) are ignored;
    works only in combination with pgid; cannot be used with pgname (see above)
  • not mandatory

 

Click tracking URL

  • key name: clcturl
  • data type: string
  • specifies an encoded click tracking URL of a third party system. Smart AdServer uses it to build the final click tracking URL => both systems can count the click
  • not mandatory

Parameters - Agency solution

Example of an agency ad tag:

<script type="text/javascript" src="http://www3.smartadserver.com/ac?pgid=609289&insid=4926771&tmstp=[timestamp]&out=js&clcturl=[countgoEncoded]">
</script>
<noscript>
<a href="http://www3.smartadserver.com/ac?jump=1&pgid=609289&insid=4926771&tmstp=[timestamp]&out=nonrich" target="_blank">
<img alt="" src="http://www3.smartadserver.com/ac?pgid=609289&insid=4926771&tmstp=[timestamp]&out=nonrich" border="0" />
</a>
</noscript>

 

Page id

  • key name: pgid
  • data type: integer
  • identifies a page under a website
  • mandatory

 

Insertion id

  • key name: insid
  • data type: integer
  • specifies the expected insertion id; works only in combination with pgid; cannot be used with pgname
  • mandatory

 

Timestamp

  • key name: tmstp OR timestamp
  • data type: numeric
  • a timestamp (unique number) used for cache busting; generated with javascript or generated by multiplying a value between 0 and 1 with 10^10
  • not mandatory

 

Output

  • key name: out
  • data type: value (e. g. out=1) or string (e. g. out=js)
  • specifies the expected output (ad response)
  • possible values: 1 or js; 2 or nonrich; 4 or iframe; 8 or xml; 16 or json
  • mandatory only for video ad calls (see below: Parameters - Video solution)

 

Click tracking URL

  • key name: clcturl
  • data type: string
  • specifies an encoded click tracking URL of a third party system. Smart AdServer uses it to build the final click tracking URL => both systems can count the click
  • not mandatory

 

Jump call

  • key name: jump
  • data type: integer
  • used for nonrich (non-javascript) calls; the click URL (href) must include jump=1
  • not mandatory

Parameters - Video solution

Example of a video ad call:

http://diff.smartadserver.com/ac?siteid=55181&pgid=570478&fmtid=29117&tgt=vpp%3Dflash%3Bvpv%3Djw6.0%3Brevision%3D90401&oc=1&ps=1&visit=M&out=vast4&vcn=c&ab=1&vpw=600&vph=338&tmstp=1454943414246

OneCall

  • key name: oc
  • data type: integer
  • oc=1 is mandatory for video ad calls

 

Output

  • key name: out
  • data type: string
  • specifies the expected output (ad response)
    out=vast2 => requests a VAST ad with version 2.0
    out=vast3 => requests a VAST ad with version 3.0 or lower
    out=vast4 => requests a VAST ad with version 4.0 or lower
  • mandatory for video ad calls

 

Ad Break

  • key name: ab
  • data type: integer
  • specifies the ad break; video insertions can be targeted to ad breaks (Placement tab in video insertions);
    values: 0 or empty; 1 for preroll; 2 for midroll; 3 for postroll
    ab= (parameter without any value) requests an overlay ad
  • not mandatory

 

Content id

  • key name: ctid
  • data type: string
  • used in the context of video syndication to specify the content where the video ad is displayed; the macro [sas_contentid] is replaced by the content id passed in the ad call 
  • not mandatory

 

Content provider id

  • key name: ctpid
  • data type: string
  • used in the context of video syndication to specify the content provider; the macro [sas_contentproviderid] is replaced by the content provider id passed in the ad call
  • not mandatory

 

Pod size

  • key name: ps
  • data type: integer
  • used in video ad calls to specify how many ads will be returned in the ad pod; max value: 20; overrides the number of instances defined on format level (read here about format instances); if the pod size parameter is present, it forces processing as a OneCall (even if only a single format id is provided); only one pod size parameter can be used per ad call and it applies for all the formats
  • not mandatory

 

Passback

  • key name: pb
  • data type: integer
  • used in video ad calls to request the number of passback ads in case the original ad cannot be delivered; maximum value is 10; pb=0 disables this behavior; if pb= is not specified, the default behavior results: 4 passback ads will be returned
  • not mandatory

 

Page domain

  • key name: pgdomain
  • data type: string
  • specifies the page domain, where the video ad call is integrated; the value is integrated by Smart AdServer's generic function
  • not mandatory

 

Video count Noad

  • key name: vcn
  • data type: string
  • used for client-side or server-side counting of noad; noad means that no ad is delivered, but that the ad call is counted for reporting and forecasting;
    vcn=c => client-side counting; used when the ad call originates from Smart AdServer's video plugin or Embedded Ad Manager
    vcn=s => server-side counting; used when the ad call originates from other sources
  • not mandatory
Was this article helpful?
2 out of 2 found this helpful
Powered by Zendesk