PRODUCT
Follow

Access to this article does not require a login on Sizmek Advertising Suite.

The article can be shared with webmasters and other users who do not have a login for Sizmek Advertising Suite.

Overview

This page explains how to use the Tag Manager API to trigger Tag Manager calls from within a web page, and how to populate parameters programmatically.

This is useful for cases in which the webmaster (or similar user) wants more control over when and how the tag manager collects the data.

Tag Manager can easily handle these types of situations:

  • You have sections of your website that generate new pages or dialogs without explicitly changing URLs.
  • You want Tag Manager to recognize these virtual pages so that you can build activity rules around them.
Important:
  • The Tag Manager API overrides Tag Manager UI settings.
  • The Tag Manager API is not supported on pages with multiple Sizmek Tag Managers.

Getting Started

Tag Manager Code Structure

Note: It is a best practice to insert Tag Manager code in the <body> of the webpage, after the optional dataLayer code. 

<script type="text/javascript">
    (function(e, d, o) {
        var c, t, n, a, i;
        o = o || {}, o.id = e, t = d.getElementsByTagName("script")[0], n = d.createElement("script"), a = [], i = encodeURIComponent;
        for (c in o) o.hasOwnProperty(c) && a.push(i(c) + "=" + i(o[c]));
        n.async = !0, n.src = (o.ptcl || "https") + "://secure-ds.serving-sys-int.com/SemiCachedScripts/ebOneTag.js", "s" !== n.src.charAt(4) && (n.src = n.src.replace("secure-", "")), n.src += "?" + a.join("&"), t.parentNode.insertBefore(n, t)
    })("1073742147", document, {
        ptcl: "http",
        dataLayer: "versatagObj",
	dispType: "iFrame",
});

</script>
Options Object
Name Limitation Description Notes
ptcl Optional

Overrides the protocol with which the tag manager will generate the call to the Sizmek server that was defined in Sizmek Advertising Suite.

Possible Values:

  • https
  • http
dataLayer Optional

Overrides the data layer name that was defined in Sizmek Advertising Suite.

Possible Values:

Any valid JavaScript variable name.

dispType Optional

Overrides the Return Server Response as that was defined in Sizmek Advertising Suite, which determines how the server returns its response.

Possible Values:

  • iFrame
  • js

Overriding Existing Configuration

Whenever the tag manager is published, a configuration file with all the tag manager configuration (such as dataLayer name and all of the variables in use) is created.

There are cases in which the webmaster does not want the tag manager to collect the data to send to Sizmek, but rather override what the tag manager collected and send different data.

The webmaster can override the configuration file settings (which is the settings that were defined on the platform) using the following code:

<codeclass="javascript">
<scripttype="text/javascript">
    (function(e, d, o){
        var c, t, n, a, i;
        o=o||{}, o.id=e, t=d.getElementsByTagName("script")[0],	n=d.createElement("script"), a=[], i=encodeURIComponent;
        for(c in o) o.hasOwnProperty(c)&&a.push(i(c)+"="+i(o[c]));
        n.async=!0,	n.src=(o.ptcl||"https")+"://secure-ds.serving-sys-int.com/SemiCachedScripts/ebOneTag.js", "s"!==n.src.charAt(4)&&(n.src=n.src.replace("secure-", "")), n.src+="?"+a.join("&"), t.parentNode.insertBefore(n,	t)
    })("1073742147", document, {
        ptcl: "http",
        dataLayer: "versatagObj",
        dispType: "iFrame",
        parameters: {
            conversion: [{
                param1: {
                    value: "1234",
                    type: "CONST"
                }
            }],
            retargeting: [{
                123456789: {
                     value: "blue",
                     type: "CONST"
                 }
            }],
            conditional: [{
                condParam: {
                    value: "abcd",
                    type: "CONST"
                }
            }]
	}
});
</script>
Parameters
Name Limitation Description Notes
conversion Optional

Array of activity parameters that will override values retrieved from the page that are meant to be used in conversion activities (triggered by the tag manager).

Structure for each activity parameter is 


%activity_param_name%: {
    value: "%activity_param_value%",
    type: "CONST"
 }
retargeting Optional

Array of retargeting activity values that will override values retrieved from the page that are meant to be used in retargeting activities (triggered by the tag manager).

Structure for each retargeting activity value is 


%retargeting_activity_id%: {
    value: "%retargeting_activity_value%",
    type: "CONST"
}
conditional Optional

Array of conditional parameters that will override values retrieved from the page that are meant to be used in an activity rule (evaluated by the tag manager).

Structure for each conditional parameter is 


%conditional_parameter_name%: {
    value: "%conditional_parameter_value%",
    type: "CONST"
}

API Methods

To use the Tag Manager JavaScript (JS) methods, it is recommended that the webmaster include the onready code below the Tag Manager code. For example:


<script type="text/javascript">
    (function(e, d, o) {
        var c, t, n, a, i;
        o = o || {}, o.id = e, t = d.getElementsByTagName("script")[0], n = d.createElement("script"), a = [], i = encodeURIComponent;
        for (c in o) o.hasOwnProperty(c) && a.push(i(c) + "=" + i(o[c]));
        n.async = !0, n.src = (o.ptcl || "https") + "://secure-ds.serving-sys-int.com/SemiCachedScripts/ebOneTag.js", "s" !== n.src.charAt(4) && (n.src = n.src.replace("secure-", "")), n.src += "?" + a.join("&"), t.parentNode.insertBefore(n, t)
    })("1073742147", document, {
        ptcl: "http",
        dataLayer: "versatagObj",
	dispType: "iFrame",
});

versaTagObj.onready(function() {
	// VersaTagObj is ready for API use - this part will override the config file
	versaTagObj.setActivityParam("key", "value");
	versaTagObj.setConditionalParam("key", "value");
	versaTagObj.setDynamicRetargetParam("key", "value");
	// Request is fired once generateRequest is called
	versaTagObj.generateRequest();
});

</script>

onready

Description

The onready method allows the webmaster to safely trigger any of the Tag Manager JS calls, while assuring that the versatagObj exists. The onready funciton is triggered once the versatagObj is created.

generateRequest

Description

The generateRequest method allows the webmaster to trigger a call to Sizmek servers.

The webmaster can use this method to trigger a call when an event happened on the page (for example, an end-user entered text to an input), or to pass a different URL, which is very useful for single page websites where the page content changes but the page URL does not change.

Example

<script type=”text/JavaScript”>
versaTagObj.onready(function(){ versaTagObj.generateRequest(“fakeURL”); }); </script>
Request Parameters
Name Limitation Description Notes
URL Optional

Allows to pass a URL that will be evaluated by the Sizmek tag manager logic engine.

  • The someVirtualUrl must include http or https depending on the protocol of the page.
  • The call should be called only after the versatagObj exists.
    To make sure it exists, it is recommended to generate the call within the onready function.

getActivityParam

Description

The getActivityParam method allows the webmaster to get a specific conversion activity parameter's value.

If there is no value for the conversion activity paramater, the function returns null.

Example

<script type=”text/JavaScript”>
versaTagObj.onready(function(){ var orderID = versaTagObj.getActivityParam("OrderID"); console.log("this is the orderID: " + orderID); }); </script>
Request Parameters
Name Limitation Description
Parameter Name Mandatory

Conversion activity parameter name from which to pull the data.

setActivityParam

Description

The setActivityParam method allows the webmaster to define a conversion activity value to a parameter, overriding the value set by the tag manager code.

Example

<script type=”text/JavaScript”>
versaTagObj.onready(function(){ var userAge = $('#age-input').val(); versaTagObj.setActivityParam("age", userAge); versaTagObj.generateRequest(); }); </script>
Request Parameters
Name Limitation Description
Parameter name Mandatory

Conversion activity parameter name into which data is populated.

Parameter value Mandatory

Value to populate into the parameter.

clearActivityParam

Description

The clearActivityParam method allows the webmaster to clear all conversion activity parameters.

Example

<script type=”text/JavaScript”>
versaTagObj.onready(function(){ versaTagObj.clearActivityParam(); versaTagObj.setActivityParam("productinfo", "the tracking band concert 09/25/2018"); versaTagObj.generateRequest(); });
</script>

getDynamicRetargetParam

Description

The getDynamicRetargetParam method allows the webmaster to get the retargeting activity value for any retargeting activity ID.

If there is no value for the retargeting activity ID, the function returns null.

Example

<script type=”text/JavaScript”>
versaTagObj.onready(function(){
    var genre = versaTagObj.getDynamicRetargetParam("30541");
    console.log("this is the retargeting value according to genre: " + genre);
});
</script>
Request Parameters
Name Limitation Description
Retargeting Activity ID Mandatory

ID of the retargeting activity that holds the data.

setDynamicRetargetParam

Description

The setDynamicRetargetParam method allows the webmaster to define a value to a retargeting activity, overriding the previous value.

Example

<script type=”text/JavaScript”>
versaTagObj.onready(function(){
    var concert_dates = $('#date-input').val()
    versaTagObj.setDynamicRetargetParam("15778", concert_dates);
    versaTagObj.generateRequest();
});
</script>
Request Parameters
Name Limitation Description
Retargeting Activity ID Mandatory

ID of the retargeting activity into which to set the value.

Retargeting Value Mandatory

Value to populate into the retargeting activity.

clearDynamicRetargetParam

Description

The clearDynamicRetargetParam method allows the webmaster to clear all retargeting activity values.

Example

<script type=”text/JavaScript”>
versaTagObj.onready(function(){
    versaTagObj.clearDynamicRetargetParam();
    versaTagObj.setDynamicRetargetParam("15778", "05/14/2018");
    versaTagObj.generateRequest();
});
</script>

getConditionalParam

Description

The getConditionalParam method allows the webmaster to retrieve a parameter that is part of an activity rule criteria.

Example

If this is the criteria:

then using getConditionalParam will allow the user get the value on the zipcode variable as seen below.


<script type=”text/JavaScript”>
versaTagObj.onready(function(){
    var zipcodeVar = versaTagObj.getConditionalParam("zipcode");
    console.log("this is the value according of the zipcode variable: " + zipcodeVar);
});
</script>
Request Parameters
Name Limitation Description
Conditional Parameter Name (name of variable in Sizmek platform) Mandatory

Name of the variable in the platform for which the webmaster wants to pull data.

For example:

setConditionalParam

Description

The setConditionalParam method allows the webmaster to set a value to a conditional parameter manually, overriding the previous value (usually set by the tag manager code).

Example

<script type=”text/JavaScript”>
versaTagObj.onready(function(){
    var userZipcode= $('#zipc').val()
    versaTagObj.setConditionalParam("zipcode", userZipcode);
    versaTagObj.generateRequest();
});
</script>
Request Parameters
Name Limitation Description
Conditional Parameter Name (name of variable in Sizmek platform) Mandatory

Name of the variable in the platform about which the webmaster wants to pull data.

For example:

Conditional Parameter Value Mandatory

Value to populate into the conditional parameter.

clearConditionalParam

Description

The clearConditionalParam method allows the webmaster to clear all conditional parameter values.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments