Salesforce

Tagging guide 1 - overview

« Go Back
Information
Tagging guide 1 - overview
Tagging-guide
Details

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 typeDescription
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                                                                                       
domainstringyesn/aDomain of the network (account) at Equativ.
networkidintegeryesemptyID of the network (account) at Equativ. 
renderModeintegerno; but required for onecall0Defines 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).
renderModeTimeoutintegerno; only for sas.renderMode.ON_DEMAND 5000 msAfter this timeout in milliseconds, sas.render() will be called.
inSequencebooleannofalseIf true, all ads are called in sequence to handle linked or excluded insertions.
uidstringnoemptyUnique 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.
appNamestringnoemptyName of your application.
bundleIdstringnoemptyUnique 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                            
standardsas.call("std", { ... })
iframesas.call("iframe", { ... })
onecallsas.call("onecall", { ... })
xmlsas.call("xml", { ... })

 

sas.call (ad)

This object defines the placement properties.
Parameter      Type         Description                                                          
siteIdIntegerthe site id, parent element of a page 
pageIdIntegerthe page id, child element of the site
pageNameStringthe page name (optional)

Note: if pageName is used, the siteId has to be present. Use of pageId is recommended.
formatIdInteger or Stringthe format id(s), eg: 1233 or "20142, 20143, 20144"; 
targetStringthe 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.
tagIdStringthe identifier of the destination container in the DOM
schainStringthe serialized SupplyChainObject
 

sas.call([options])

This object that defines the call options.
Option                 Type        Description                                                                                                                                            
forceMasterFlagbooleanForces 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
resetTimestampbooleanResets 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
resetbooleanWorks with OneCall tag only. Resets all sas.render(tagId) done for all formats in the given list.

Default value: false
clickTrackingUrlstringAdds 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
clickTrackingEncodingLevelintegerSets 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
onLoadfunctionCallback called after call has been done, only available in async mode.
onErrorfunctionCallback called if an error occurred during the call.
onClean(formatId, element)functionCallback 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)functionCallback 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)functionCallback 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;
getAdContentbooleanSpecifies 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.
eidsArray of ObjectContaining the extended ids for a user
  
  • source – String, id provider;
  • value – String, user id;

 

Powered by