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

    Tagging guide: implementation

    Table of Contents

    Overview OneCall tagging with HTTP POST request method Example Options method OPTIONS response sample CORS Headers The following headers are sent: Rendering a format Example Setting global and tagId specific keyword targeting in OneCalls Standard tagging Examples Calling a format multiple times Other operations Cleaning ads Example Calling ads in an iframe Example Managing ad responses (onAd) OneCall tagging example Standard tagging example Managing empty ad responses (onNoad) Standard tagging example Calling ads over HTTPS CNAME security warning

    Overview 

    This article describes implementation examples of Equativ ad tags for both OneCall and Standard call implementations.

    OneCall tagging with HTTP POST request method

    With OneCall tagging, you can call all the formats of a given page in a single call, rather than each format separately.  OneCall tags use the HTTP POST request method rather than HTTP GET: information is sent in the request body and the response is a JSON object which contains a list of insertion URLs per tagId. 

    In order to call a format with a specific tagId, you must call the sas.render() function as explained in section “Rendering a format” below. 

    Note that the OneCall tag using the HTTP POST request method also allows you to do multiple OneCalls on the same page with none of them overwriting each other. The OneCall tag using the HTTP POST request method uses an array "formats" of format objects in the sas.call function:

    Property           Data type Description
    currency string the currency of the overridden bidfloor ('EUR', 'USD', etc.)
    id integer the format id; mandatory
    overriddenBidfloor decimal used to set an overridden bid floor for the given format (this bid floor will override the bid floor calculated usually)
    tagId string the tag of the container of the page that will contain the ad

    Example

    Example of a OneCall generic script, to be placed in the <head> of the page:

    <script type="application/javascript" src="https://ced.sascdn.com/tag/73/smart.js" async></script>
<script type="application/javascript">
    var sas = sas || {};
    sas.cmd = sas.cmd || [];
    sas.cmd.push(
        function() {
            sas.setup({ networkid: 73, domain: "https://diff.smartadserver.com", async: true });
            sas.call("onecall", {
                siteId: 12345,
                pageId: 678910,
                formats: [
                { id: 25350 }
                ,{ id: 58153 }
                ,{ id: 24154 }
                ],
                target: ''
            });
        });
</script>

    Example of a OneCall ad tag to be placed in the <body> of the page: 

    <div id="sas_25350"></div>
<script type="application/javascript">
    sas.cmd.push(function() {
        sas.render("25350");  // Format : myformat 1x1
    });
</script>

    Options method

    The OPTIONS method is a preflight request sent by some browsers to verify what they are allowed to do in the following POST request. It does not have any impact on the tagging. OPTIONS request sample 

    OPTIONS http://[subDomain].smartadserver.com/2693/call HTTP/1.1
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type
Origin: http://publisher.com

    OPTIONS response sample 

    HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: http://publisher.com
Access-Control-Allow-Methods: GET, HEAD, POST
Access-Control-Allow-Headers: content-type

    CORS Headers The following headers are sent: 

    Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: <referrer_of_adcall>

    Rendering a format

    To render a format, call the method sas.render([formatId/tagId]) method. This method can be called either with a 

    • formatId (string or number) - or
    • tagId. In this case, the mapping between the formatId and the tagId must be specified in sas.call, for instance:
    sas.call('onecall', {
siteId: 12345,
pageId: 12345,
formats: [
{ id: 1234, tagId: 'sas_1234' },
{ id: 4567, tagId: 'sas_4567' }
],
target: ''
});

    Calling sas.render with a formatId or a tagId is also supported in case of formats with instances. Make sure you attach “_x” to the formatId/tagId, replacing x by the instance number. 

    Example 

    If formatId 1234 has 3 instances, you can call the instances using the formatId as follows: 

    •  sas.render("1234") 
    •  sas.render("1234_2")
    •  sas.render("1234_3")

    Alternatively, you can call the the instances using the corresponding tagId as follows: 

    •  sas.render("sas_1234") 
    •  sas.render("sas_1234_2")
    •  sas.render("sas_1234_3")

    The table below describes if sas.render() is executed automatically without arguments, depending on the call type and render mode in use:   

    Call type Render mode sas.render() called automatically?
    OneCall renderMode 0 (default) no
    OneCall renderMode 1 yes
    OneCall renderMode 2 yes, unless it is called manually within 5 seconds
    Standard Call renderMode 0 (default) no
    Standard Call renderMode 1 yes
    Standard Call  renderMode 2 yes, unless it is called manually within 5 seconds

    For more details about the render mode, see section “Set up the ad manager – sas.setup(options)” in the Tagging guide: get started article. 

    The example below renders the formatId 14968. 

    <script type="application/javascript">
 sas.render('14968'); // Format : myformat
</script>

    The example below calls the method sas.render without any parameter. This triggers the rendering when renderMode is set to 2 (render ad on demand). 

    // will render the format id 12345
sas.render(12345);
// will trigger the rendering if renderMode is 2 (render ad on demand)
sas.render();

    The callback beforeRender(data) is called before the format rendering (sas.render method). The callback is only called if the oneCall has produced a successful response.    

    beforeRender(data) could be used to execute javascript in case of empty ad responses (noad). However, the onNoad(data) callback function is the recommended method for this purpose (read the "Managing empty ad responses (noad)" chapter below).

     

    Setting global and tagId specific keyword targeting in OneCalls

    In OneCalls, you can set keyword targeting criteria on two levels:

    • on tagId level, to be applied for the given tagId – see keywordA=value1 for tagId: "sas_tag_001" and keywordB=value2 for tagId: "sas_tag_002" in the example below
    • on global level, to be applied for all tagIds, set at the root level of sas.call(); see keywordA=value3 in the example below

    Example 

    sas.call("onecall", {
  siteId: 1234,
  pageId: 5678,
  formats: [{
      id: 84313,
      tagId: "sas_tag_001"
      target: 'keywordA=value1'
  },
  {
      id: 84313,
      tagId: "sas_tag_002"
      target: 'keywordB=value2'
  }],
  target: 'keywordA=value3'
});

    The following rules apply:

    • by default, key=values defined on global level are applied for all tagIds in addition to other key=values defined for individual tagIds; the key=values defined on global level are appended to the key=values defined for each tagId
    • if you define the same key (e. g. keywordA=) on global level and on tagId level, then the value on tagId level will take priority over the value defined on global level; for instance, for tagId: "sas_tag_001" in the example above, the value1 will take priority over the global value3 . 

    The example mentioned above would generate the following request: 

    "ads": [{
  "formatId": 84313,
  "tagId": "sas_tag_001",
  "target": "keywordA=value1",
  "headerBidding": {},
  "isLazy": false,
  "isAdRefresh": 0
}, {
  "formatId": 84313,
  "tagId": "sas_tag_002",
  "target": "keywordA=value3;keywordB=value2",
  "headerBidding": {},
  "isLazy": false,
  "isAdRefresh": 0
}],

    Standard tagging

    Standard ad tags are not recommended for new integrations. Use OneCall ad tags instead. 

     

    To use standard tagging, you need to:

    • call sas.setup (with the mandatory domain parameter) and
    • call sas.call(<call type>, <options>) with the call type std (for "standard").

    Examples

    Example of a Standard tagging generic script to be placed into the <head> of the page:

    <script type="application/javascript" src="https://ced.sascdn.com/tag/73/smart.js" async></script>
<script type="application/javascript">
    var sas = sas || {};
    sas.cmd = sas.cmd || [];
    sas.cmd.push(function() {
        sas.setup({ networkid: 73, domain: "https://diff.smartadserver.com", async: true });
    });
</script>

    Example of a Standard ad tag to be placed into the <body> of the page: 

    <div id="sas_146032"></div>
<script type="application/javascript">
    sas.cmd.push(function() {
        sas.call("std", {
            siteId: 46374, // 
            pageId: 3648932, // Page : my_site/my_page (PageID=3648932)
            formatId: 146032, // Format : myformat 1x1
            target: '' // Targeting
        });
    });
</script>
<noscript>
    <a href="https://diff.smartadserver.com/ac?jump=1&nwid=73&siteid=46374&pgname=mypage&fmtid=146032&visit=m&tmstp=[timestamp]&out=nonrich" target="_blank">
        <img src="https://diff.smartadserver.com/ac?out=nonrich&nwid=73&siteid=46374&pgname=mypage&fmtid=146032&visit=m&tmstp=[timestamp]" border="0" alt="" />
    </a>
</noscript>

    Calling a format multiple times

    For OneCall tagging see the “Rendering a format” chapter above. 

     

    In some cases you may want to call the same format multiple times on a given page. For instance, you may want to call two medium rectangles (with the same formatId) on a page: one at the top and one at the bottom of the page.   

    Use the tagId option in the sas.call method to make sure that the ads appear in the correct <div> containers. In this method, you specify the Ids of the containers, where the format is supposed to be displayed. 

    Warning Calling a format multiple times with standard call is not recommended if your setup is using insertion links, exclusions or multi-format insertions (insertions activated on multiple formats) — the proper functioning of these features cannot be guaranteed. In these cases, use OneCall instead of standard call.    

     

    The example below calls the formatId 146032 and displays it in the div with id 'medrec-top'.

    <script type="application/javascript">
    sas.cmd.push(function() {
        sas.call("std", {
            siteId: 46374, // 
            pageId: 3648932, // Page : my_site/my_page (PageID=3648932)
            formatId: 146032, // Format : myformat 1x1
            target: '' // Targeting
            tagId: 'medrec-top'
        });
    });
</script>

    To call the format and display it in another div, simply replace the tagId (e. g. replace 'medrec-top' by  'medrec-bottom'). 

    Other operations

    Cleaning ads

    This option is available for both OneCall and Standard tagging types. To clean a specific format, use the sas.clean([formatId]) method. Calling the method without any specified formatId will clean all the formatIds of the page. 

     

    Example

    // clean the format 300
sas.clean(300);
 
// clean all formats
sas.clean();

    When using the sas.clean method, the callback onClean(formatId, element) in the sas.call method will be triggered: 

    • formatId (integer): the Id of the cleaned format
    • element (DOM element): the format DOM element container which will be cleaned

    You can register a function to be warned when a clean has been executed.   

    Calling ads in an iframe

    To call ads in an iframe, change the callType from "std" to "iframe" and specify the width and height of the iframe. 

    Example

    <script type="application/javascript">
    sas.call("iframe", {
            siteId: 53008,
            pageName: 'mypage',
            formatId: 23028,
            tagId: 'sas_23028',
            height:300,
            width:250
    });
</script>

    Managing ad responses (onAd)

    The onAd(data) callback function is triggered when Equativ returns an ad to be displayed for a given format. You can use this callback function to execute javascript code on your website when Equativ's response contains an ad. 

    The onAd(data) callback function has the properties: 

    • data.tagId, (string): the tag id of the ad
    • data.formatId, (string): the format id of the ad

    OneCall tagging example

    <!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>DEMO TAGS</title>
    <script src="//ced.sascdn.com/tag/620/smart.js" type="application/javascript" async></script>
    <script type="application/javascript">
        var sas = sas || {};
        sas.cmd = sas.cmd || [];
        sas.cmd.push(function () {
            sas.setup({ networkid: 174, domain: "//[subdomain].smartadserver.com", async: true });
        });
        sas.cmd.push(function () {
            sas.call("onecall", {
                siteId: 86374,
                pageId: 609161,
                formats: [{
                    id: 36780
                }],
                target: ''
            }, {
                onAd: function (data) {
                    if (data.formatId) {
                        console.log(data);
                        console.log("FORMAT ID : " + data.formatId);
                        console.log("TAG ID : " + data.tagId);
                    }
                }
            });
        });
    </script>
</head>
<body>
    <div id="sas_36780"></div>
    <script type="application/javascript">
        sas.cmd.push(function () {
            sas.render("36780"); // Format : billboard 750x300
        });
    </script>
</body>
</html>

    Standard tagging example

    <!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>DEMO TAGS</title>
    <script src="//ced.sascdn.com/tag/620/smart.js" type="application/javascript" async></script>
<script type="application/javascript">
    var sas = sas || {};
    sas.cmd = sas.cmd || [];
    sas.cmd.push(function() {
        sas.setup({ networkid: 620, domain: "//[subdomain].smartadserver.com", async: true });
    });
</script>
</head>
<body>
<div id="sas_36780"></div>
<script type="application/javascript">
    sas.cmd.push(function() {
        sas.call("std", {
            siteId: 86374,
            pageId: 609161,
            formatId: '36780',
            target: ''
        }, {
            onAd: function(data){
                if (data.formatId) {
                    console.log(data);
                    console.log("FORMAT ID : "+data.formatId);
                    console.log("TAG ID : "+data.tagId);
                }
            }
        });
    });
</script>
</body>
</html>

    Managing empty ad responses (onNoad)

    The onNoad(data) callback function is triggered if there is no ad to display for the given format (empty ad response). You can use this callback function to execute javascript code on your website when an ad request does not return any ad.   

    In case of callType="onecall", the callback will be triggered for each empty format.   

    The onNoad(data) callback function has the properties: 

    data.tagId, (string): the tag id of the noad

    data.formatId, (string): the format id of the noad

    Standard tagging example

    <!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>DEMO TAGS</title>
    <script src="//ced.sascdn.com/tag/620/smart.js" type="application/javascript" async></script>
<script type="application/javascript">
    var sas = sas || {};
    sas.cmd = sas.cmd || [];
    sas.cmd.push(function() {
        sas.setup({ networkid: 620, domain: "//[subdomain].smartadserver.com", async: true });
    });
</script>
</head>
<body>
<div id="sas_36780"></div>
<script type="application/javascript">
    sas.cmd.push(function() {
        sas.call("std", {
            siteId: 86374,
            pageId: 609161,
            formatId: '36780',
            target: ''
        }, {
            onNoad: function(data){
                if (data.formatId) {
                    console.log(data);
                    console.log("FORMAT ID : "+data.formatId);
                    console.log("TAG ID : "+data.tagId);
                }
            }
        });
    });
</script>
</body>
</html>

    Calling ads over HTTPS

    The ad tags you can export from the user interface are already HTTPS compatible. They use a schema-less URI model and can be used on HTTP and HTTPS websites directly. 

    If your website (page) is loaded over HTTPS, browser security requires the following: 

    • Equativ ad tags must be called with HTTPS 
    • Third party ad tags (agency scripts pasted on the Creatives tab of insertions) must be called with HTTPS the 
    • Landing pages (clickURLs) must be secure (HTTPS) 

    Failing to do so leads to a security error in the browser (negative impact on user experience)! 

     

    CNAME security warning

    You can use a CNAME to have an advertising subdomain on your own domain (e. g. ads.mydomain.com) while still pointing to Equativ's servers; when doing so, make sure that your advertising subdomain does not get access to your first party cookies; especially, the advertising subdomain (ads.mydomain.com) must not get access to any authentication token stored on your main domain (mydomain.com).

     

     

     

    RELATED ARTICLES