Salesforce

Tagging guide 2 - implementation

Printable View
« Go Back
Information
Tagging guide 2 - implementation
Tagging-guide-2-implementation
Details

Overview

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

Related articles

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 typeDescription
idintegerthe format id; mandatory
tagIdstringthe tag of the container of the page that will contain the ad
overriddenBidfloordecimalused to set an overridden bid floor for the given format (this bid floor will override the bid floor calculated usually)
currencystringthe currency of the overridden bidfloor ('EUR', 'USD', etc.)
 

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 typeRender modesas.render() called automatically?
OneCallrenderMode 0 (default)no
OneCallrenderMode 1yes
OneCallrenderMode 2yes, unless it is called manually within 5 seconds
Standard CallrenderMode 0 (default)no
Standard CallrenderMode 1yes
Standard Call renderMode 2yes, 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 1 - overview 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

Note: 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

Note: 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).
Powered by