Contact support
    • Monetization
    • Developer documentation
    • Supply inventory
    • Supply inventory with web ad tags

    Tagging guide: get started

    Table of Contents

    Overview Ad tags Generate ad tags Ad tag types Set up the ad manager – sas.setup(options) Call ads – sas.call sas.call (callType) sas.call (ad) sas.call([options])

    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. 

    Ad tags 

    Generate ad tags

    For instructions on generating ad tags, see the "Ad tags" section in the Create placements article.

    Ad tag types

    This table describes all the display (web) ad tags available in the Equativ platform.

    Ad tag type Description
    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)
    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)
    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
    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)

    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                                                                                       
    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.
    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.
    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.

    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                            
    iframe sas.call("iframe", { ... })
    onecall sas.call("onecall", { ... })
    standard sas.call("std", { ... })
    xml sas.call("xml", { ... })

    sas.call (ad)

    This object defines the placement properties.

    Parameter       Type          Description                                                          
    formatId Integer or String the format id(s), eg: 1233 or "20142, 20143, 20144"; 
    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.
    schain String the serialized SupplyChainObject
    siteId Integer the site id, parent element of a page 
    tagId String the identifier of the destination container in the DOM
    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 Set keyword targeting.

    sas.call([options])

    This object that defines the call options.

    Option                  Type         Description                                                                                                                                            
    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);
    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
    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
    eids Array of Object

    Containing the extended ids for a user 

      

    • source – String, id provider;
    • value – String, user id;
    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
    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.
    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;
    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;
    onError function Callback called if an error occurred during the call.
    onLoad function Callback called after call has been done, only available in async mode.
    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;
    reset boolean

    Works with OneCall tag only. Resets all sas.render(tagId) done for all formats in the given list.

     

    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

     

    RELATED ARTICLES