Note
Note: Access to this article does not require a login on Amazon Ad Server (AAS).
The article can be shared with webmasters and other users who do not have a login for AAS.
Important
Important: Code snippets in this article are just examples. Please use your own Tag Manager code and adjust it according to the examples.
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 a 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
Important:
The Tag Manager API overrides Tag Manager UI settings.
The Tag Manager API is not supported on pages with multiple AAS Tag Managers.
Note
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) })("1111111111", document, { ptcl: "http", dataLayer: "versatagObj", dispType: "iFrame", }); < /script>
Name |
Limitation |
Description |
Notes |
ptcl |
Optional |
Overrides the protocol with which the Tag Manager will generate the call to the AAS server that was defined in AAS. |
Possible Values:
|
dataLayer |
Optional |
Overrides the data layer name that was defined in AAS. |
Possible Values: Any valid JavaScript variable name. |
dispType |
Optional |
Overrides the Return Server Response as that was defined in AAS, which determines how the server returns its response. |
Possible Values:
|
In order to enable path to conversion (P2C) reporting through Tag Manager, a call shall include a pseudonymous user cookie or advertiser device ID. In case a cookie is not available, Tag Manager will use the advertiser device ID token.
AdvertiserDeviceId token is included in cn=ot requests fired from Tag Manager.
To set it , the advertiserDeviceId token should be added to the tag’s options object as follows:
<script type="text/javascript"> (function(e, s, t) { t = t || {}, t.id = e, versaTagObj = { $: [], onready: function(e) { this.$.push(e) } }; var n = s.getElementsByTagName("script")[0], r = s.createElement("script"); r.options = t, r.async = !0, r.src = "https://secure-ds.serving-sys.com/SemiCachedScripts/ebOneTag.js?id=" + e, r.options = t, n.parentNode.insertBefore(r, n) })("OneTag_ID", document, { dataLayer:"SizmekDataLayer", advertiserDeviceId: "Device_ID" });</script>
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 AAS, but rather override what the Tag Manager collected and send different data.
The webmaster can override the configuration file settings (which are the settings that were defined in AAS) or set values for parameters using the following code:
<script type = "text/javascript" > (function(e, s, t) { t = t || {}, t.id = e, versaTagObj = { $: [], onready: function(e) { this.$.push(e) } }; var n = s.getElementsByTagName("script")[0], r = s.createElement("script"); r.options = t, r.async = !0, r.src = "https://secure-ds.serving-sys.com/SemiCachedScripts/ebOneTag.js?id=" + e, r.options = t, n.parentNode.insertBefore(r, n) })("920", document, { ptcl: "https", dataLayer: "versatagObj", dispType: "js", parameters: { retargeting: [{ 44791: { value: _satellite.getVar('contentTitle'), type: "CONST" }}], conversion: [{ param1: { value: "", type: "" } }], conditional: [{ condParam: { value: "", type: "" } }] } }); </script>
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
|
retargeting |
Optional |
Array of retargetingand/or dynamic retargeting activity values that will override values retrieved from the page that are meant to be used in retargeting or dynamic retargetingactivities (triggered by the Tag Manager). |
Structure for each retargeting activity value is
|
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
|
To use the Tag Manager JavaScript (JS) methods, it is recommended that a 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>
The generateRequest method allows the webmaster to trigger a call to AAS 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 whether the page URL does or does not change.
<script type="text/JavaScript">
versaTagObj.onready(function(){
versaTagObj.generateRequest("fakeURL");
});
</script>
Name |
Limitation |
Description |
Notes |
URL |
Optional |
Allows to pass a URL that will be evaluated by the AAS tag manager logic engine. |
|
The getActivityParam method allows the webmaster to get a specific conversion activity parameter's value.
If there is no value for the conversion activity parameter, the function returns null.
<script type="text/JavaScript">
versaTagObj.onready(function(){
var orderID = versaTagObj.getActivityParam("OrderID"); console.log("this is the orderID: " + orderID);
});
</script>
The setActivityParam method allows the webmaster to define a conversion activity value to a parameter, overriding the value set by the Tag Manager code.
<script type="text/JavaScript">
versaTagObj.onready(function(){
var userAge = $('#age-input').val();
versaTagObj.setActivityParam("age", userAge);
versaTagObj.generateRequest();
});
</script>
The clearActivityParam method allows the webmaster to clear all conversion activity parameters.
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.
<script type="text/JavaScript">
versaTagObj.onready(function(){
var genre = versaTagObj.getDynamicRetargetParam("30541");
console.log("this is the retargeting value according to genre: " + genre);
});
</script>
The setDynamicRetargetParam method allows the webmaster to define a value to a retargeting activity, overriding the previous value.
<script type="text/JavaScript">
versaTagObj.onready(function(){
var concert_dates = $('#date-input').val()
versaTagObj.setDynamicRetargetParam("15778", concert_dates);
versaTagObj.generateRequest();
});
</script>
The clearDynamicRetargetParam method allows the webmaster to clear all retargetingactivity values.
The getConditionalParam method allows the webmaster to retrieve a parameter that is part of an activity rule criteria.
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>
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).
<script type="text/JavaScript">
versaTagObj.onready(function(){
var userZipcode= $('#zipc').val()
versaTagObj.setConditionalParam("zipcode", userZipcode);
versaTagObj.generateRequest();
});
</script>
Comments