Overview
This guide is addressed to web developers. It describes the available ad tag types available in Equativ’s Monetization Platform (EMP) as well as the main functions and options to configure the tagging.
Related articles
Ad tags
Generate ad tags
For instructions on generating ad tags, see the "Ad tags" section in the
Setting up inventory article.
Ad tag types
This table describes all the display (web) ad tags available in the Equativ platform.
Ad tag type | Description |
---|
OneCall |
- used to call all formats on a page in a single call ("OneCall")
- Important: OneCall is the recommended ad tag type for integrations of Equativ ad tags on websites
- consists of a generic script (to be placed in the <head> of the page) and one ad tag per format on the page (to be placed in the <body> of the page)
|
Standard |
- used to call each format of a page one by one (as opposed to OneCall)
- ⚠ Warning: not recommended for new integrations – use OneCall instead
- consists of a generic script (to be placed in the <head> of the page) and one ad tag per format on the page (to be placed in the <body> of the page)
|
Standalone |
- used to make a third party system (e. g. a publisher ad server) call ads from Equativ; in the third party system, the Standalone tag is used as a redirect tag (also known as “agency tag”)
- usage in an HTML page recommended only if none of the other tag types can be used
- consists of one javascript tag per format on the page
|
NonRich |
- used to retrieve ads in environments where javascript cannot be used
- consists of one HTML ad tag per format on the page, including an image source (img src) and a click url (a href)
|
Set up the ad manager – sas.setup(options)
Prior to calling any ad, the
sas object must be initialized, using the
sas.setup(options) method. It must be called only once.
The table below describes the available options.
Option name | Type | Mandatory | Default value | Description |
---|
domain | string | yes | n/a | Domain of the network (account) at Equativ. |
networkid | integer | yes | empty | ID of the network (account) at Equativ. |
renderMode | integer | no; but required for onecall | 0 | Defines how ads are rendered. Values:
- sas.renderMode.DEFAULT (0) => render as soon as the ad is ready
- sas.renderMode.READY (1) => render ad as soon as the document is ready (deprecated, not recommended; either use the default (0) or handle the display using render mode 2)
- sas.renderMode.ON_DEMAND (2) => render the ad on demand; sas.render() must be called to trigger rendering (previously, sas.callAds() which is now deprecated).
|
renderModeTimeout | integer | no; only for sas.renderMode.ON_DEMAND | 5000 ms | After this timeout in milliseconds, sas.render() will be called. |
inSequence | boolean | no | false | If true, all ads are called in sequence to handle linked or excluded insertions. |
uid | string | no | empty | Unique identifier which overrides the unique id in Equativ's pid-Cookie. It is used when devices cannot be identified with cookies (e.g. in mobile apps with Equativ's iOS or Android SDK); Make sure this id is big enough to avoid id collisions. Also this parameter will be considered as IFA (the device identifier) if the adcall is considered as in-app – i.e. in cases where there is appName and bundleId present in the adcall. |
appName | string | no | empty | Name of your application. |
bundleId | string | no | empty | Unique identifier; The most recommended pattern is a reverse domain name notation. Make sure bundleId is unique to avoid collisions. |
Call ads – sas.call
Once
sas.setup is called, ads can be retrieved by calling the
sas.call (callType, ad, [options])
sas.call (callType)
The library supports the following call types:
Call type | Call |
---|
standard | sas.call("std", { ... }) |
iframe | sas.call("iframe", { ... }) |
onecall | sas.call("onecall", { ... }) |
xml | sas.call("xml", { ... }) |
sas.call (ad)
This object defines the placement properties.
Parameter | Type | Description |
---|
siteId | Integer | the site id, parent element of a page |
pageId | Integer | the page id, child element of the site |
pageName | String | the page name (optional) Note: if pageName is used, the siteId has to be present. Use of pageId is recommended. |
formatId | Integer or String | the format id(s), eg: 1233 or "20142, 20143, 20144"; |
target | String | 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 Keyword targeting. |
tagId | String | the identifier of the destination container in the DOM |
schain | String | the serialized SupplyChainObject |
sas.call([options])
This object that defines the call options.
Option | Type | Description |
---|
forceMasterFlag | boolean | Forces the master flag, which is used for page view counting. If the master flag is true, the ad call returns an ad (as usual) and the ad call is logged and reported as a page view (page impression). Default value: false |
resetTimestamp | boolean | Resets the timestamp, which is used for features such as links (displaying ads from insertions always together on a page) or exclusions (never display ads from certain insertions together on a page). Default value: false |
reset | boolean | Works with OneCall tag only. Resets all sas.render(tagId) done for all formats in the given list. Default value: false |
clickTrackingUrl | string | Adds a 3rd party click tracking URL; Note: There are different kinds of clickTrackingUrls, e.g.:
- http://core.iprom.net/Click?debug=1&ignore_track=1&redirect= – the query parameter redirect is at the end, and has no value. It is used when the 3rd party click tracker redirects further (e.g. back to smartadserver.com to count clicks). In this case clickTrackingEncodingLevel (described below) should be set to 1 (or more). Otherwise, the URL will not be encoded and the redirect mechanism will not work properly leading to data loss and thus degraded reporting.
- http://www3.smartadserver.com/h/cc?imgid=25725146&tmstp=[timestamp]&tgt=[reference] – there is no query parameter to be filled, thus clickTrackingEncodingLevel (described below) should be set to 0, which is a default value, so it can be omitted completely.
Default value: empty |
clickTrackingEncodingLevel | integer | Sets the encoding level for the clickTrackingUrl option. The parameter indicates the number of times that the click URL must be encoded before appending it to the 3rd party click tracking URL. For instance, clickTrackingEncodingLevel=2 means that the click URL is encoded twice. Default value: 0 |
onLoad | function | Callback called after call has been done, only available in async mode. |
onError | function | Callback called if an error occurred during the call. |
onClean(formatId, element) | function | Callback called before cleaning the placement
- formatId – Integer, the cleaned format Id;
- element – the format DOM element container which will be cleaned;
|
beforeRender(data) | function | Callback called before the format rendering (sas.render). The callback is only called when onecall call has returned. If sas.render is called before the onecall has returned (sas_manager created), beforeRender won't be called.
- data – Object, contains the rendering context (formatId, tagId);
|
onNoad(data) | function | Callback called if there is no ad to display for the given format, if provided for callType="onecall", callback will be triggered for each empty format.
- data.tagId – String, the tag id of the noad;
- data.formatId – String, the format id of the noad;
|
onAd(data) | function | Callback called when there is an ad returned in the response of the adserver.
- data.tagId – String, the tag id of the ad;
- data.formatId – String, the format id of the ad;
|
getAdContent | boolean | Specifies whether a onecall should return the ad content or nshowUrl;
- true: returns the ad content;
- false: returns the nshow urls;
Warning: Works only with the new OneCall tag. Returning all ad content means that RTB ads will be resolved (if any), no matter if you intend to display a format or not. This may decrease the delivery rate. |
eids | Array of Object | Containing the extended ids for a user
- source – String, id provider;
- value – String, user id;
|