PRODUCT

Amazon Ad Server will be sunset in Q4 2024, please visit this page (AAS offboarding information) for offboarding support resources and sunset FAQs. Details shared on that page represent the most up to date information in the Help Center, if you find disparate information in other resources please default to the information in the AAS offboarding information page accordingly.

Please note that on October 1, 2024, the ability to create new campaigns, placements and tag managers was disabled.

Follow

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.

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

Getting started

Tag Manager code structure

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>           

Options Object

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:

  • https

  • http

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:

  • iFrame

  • js

Include advertiser device ID in OneTag

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>

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

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


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

          

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

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 AAS tag manager logic engine.

  • The someVirtualUrl must include https depending on the protocol of the page.

  • Use this URL as page URL in the activity rule to trigger an activity rule

  • 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 parameter, 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 reporting 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 retargetingactivity 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:

VariableInActivityRule.gif

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 AAS)

Mandatory

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

For example:

VariableZipcode.gif

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 AAS)

Mandatory

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

For example:

VariableZipcode.gif

Conditional Parameter Value

Mandatory

Value to populate into the conditional parameter.

clearConditionalParam

Description

The clearConditionalParam method allows the webmaster to clear allconditional parameter values.

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

Comments