Embed Size (px)
Citation preview
Webmaster’s guide to VersaTag
Webmaster’s guide to VersaTagContents
What is VersaTag? Page 2
What do the key benefits to VersaTag include? Page 2
How should we best implement VersaTag? Page 3
What is the structure of the VersaTag code? Page 4
What are the pros and cons of synchronous and asynchronous tags? Page 6
Where in the <body> section should I place the VersaTag code? Page 7
How does VersaTag handle URL Query Strings? Page 8
What are VersaTag API Calls? Page 8
How does VersaTag handle Virtual Pages? Page 8
How does VersaTag handle Flash Pages and Events? Page 10
How does Versatag work with OnPage actions (buttons, forms)? Page 12
Does VersaTag support organic or paid search? Page 14
Does VersaTag support Website analytics tags? Page 14
How should VersaTag be deployed across multiple domains? Page 14
How can VersaTag work across different environments – for instance, a Staging and Production environment? Page 14
How can I effectively audit the migration of tags into VersaTag? Page 15
Will VersaTag run on a site that is not Javascript enabled? Page 16
Can VersaTag access the DOM to define when tags will fire? Page 16
How do I use VersaTag with an embedded YouTube video? Page 17
Will VersaTag negatively impact my site performance? Page 17
Is VersaTag private and secure? Page 17
What should I do if I have a site with a mix of secure and unsecure pages? Page 18
Can I place VersaTag into another Tag Management system? Page 19
How do I access the VersaTag test page? Page 19
Page 1
Page 2
VersaTagWebmaster’s Guide
What is VersaTag?
Sizmek’s VersaTag is a single and secure tool to deploy, manage and update all the digital marketing tags on an advertiser’s site without having to constantly update the website’s code. Best Practice for implementing the VersaTag code is to do a single deployment: the code is placed in a standard location (usually either the top or bottom of the <Body> section) within the template(s) of the site’s Content Management System (CMS). For your reference, a list of CMS systems can be found here: http://en.wikipedia.org/wiki/List_of_content_management_systems:
After that, all new conversion, retargeting and 3rd party tags can be easily managed within the VersaTag UI. The UI gives the tag administrator the power to control which tags fire on which pages. There should be no further need to touch the website in order to implement most new tagging requirements!
What do the key benefits to VersaTag include?
• Significant simplification to deployment and management of advertising tags.
• An easy, platform-integrated interface to map specific URLs tag.
• Secure alert system to monitor page view drops.
What do the key benefits to VersaTag include?
• Significant simplification to deployment and management of advertising tags.
• An easy, platform-integrated interface to map specific URLs tag.
• Secure alert system to monitor page view drops.
ConversionTag
RetargetingTag
Third-partyTag
AdvertiserPage
AdvertiserPage
AdvertiserPage
VersaTag
ConversionTag
RetargetingTag
Third-partyTag
AdvertiserPage
AdvertiserPage
AdvertiserPage
Without VersaTags, multiple tags are placed on multiple pages
With VersaTags, multiple tags are mapped to one VersaTag, and the VersaTag is placed in the site’s CMS template
Page 3
How should we best implement VersaTag?
VersaTag can be deployed through a simple six-step process:
1. Determine your Tagging Needs. Work together with your Agency and Sizmek client service manager to perform an audit of your campaigns and website. The agency/marketers should determine requirements around conversion, retargeting, 3rd party tags, business rules, attribution, special domain structure, restricted pages, permissions, tag parameter requirements, dynamic pages, conversions embedded within Flash and OnAction-based conversions.
2. Configure and Deploy VersaTag Code. Once requirements have been defined, a VersaTag deployment strategy is formulated. The VersaTag is then configured by a Sizmek client service manager. The tagging code is generated and provided to the webmaster who places it in the <body> section of your website’s main templates on the CMS. Typically, where you place VersaTag in <body> section depends on whether you configure VersaTag for asynchronous or synchronous mode. For a more thorough explanation of the difference, see the section “What are the pros and cons of synchronous and asynchronous tags?”
Also, if external parameters need to be passed into VersaTag, for use by one of the contained conversion, retargeting or 3rd party tags, you will want to also insert code to pull and process any of this external page data prior to invoking VersaTag. VersaTag and its supporting code should be deployed to all your website’s pages. The agency should provide a comprehensive list of custom parameters that they intend to use to the Sizmek account manager so that they are able to configure VersaTag to accept them.
For marketers: when passing these parameters to your Sizmek account manager, please provide the following information:
• Parameter Name
• Type (Is it an Activity/Conversion Parameter, Retargeting Parameter or Conditional Parameter – for more info on parameter types, please refer to the section “What is the structure of the VersaTag code?”
• Desired order of the parameters (the order that you provide your account manager should be the same as the order you pass them into VersaTag)
• Parameter’s datatype – is it a number, date or string
3. Review VersaTag administrative and tagging procedures. Set up VersaTag’s user permissions. Review and formalize a procedure with your media agency on how you want them to notify you if they need new tags introduced. You will want to especially discuss any new 3rd party tags and assess its potential impact on page load performance.
4. Create mapping rules. You and your agency set up mapping rules to map one or more web pages to their corresponding Conversion or Retargeting tags. To simplify the mapping process, VersaTag gives you the flexibility to group related pages together with wildcards, or import them into the system with Excel.
5. Test VersaTag Mapping. Once VersaTag has been deployed on the site, you can use VersaTag’s debug and auditing tool to test the reliability of the mapping or tag deployment while navigating the site.
6. Migrate existing tags from site into VersaTag. Once VersaTag is set up, you will want to migrate all your site’s old tags into VersaTag’s container. This is important so that these tags aren’t called twice in error. To facilitate this migration process, VersaTag includes a comprehensive mapping report, which allows you to track and audit the progress of your migration.
How should we best implement VersaTag?
VersaTag can be deployed through a simple six-step process:
1. Determine your Tagging Needs. Work together with your Agency and Sizmek client service manager to perform an audit of your campaigns and website. The agency/marketers should determine requirements around conversion, retargeting, 3rd party tags, business rules, attribution, special domain structure, restricted pages, permissions, tag parameter requirements, dynamic pages, conversions embedded within Flash and OnAction-based conversions.
2. Configure and Deploy VersaTag Code. Once requirements have been defined, a VersaTag deployment strategy is formulated. The VersaTag is then configured by a Sizmek client service manager. The tagging code is generated and provided to the webmaster who places it in the <body> section of your website’s main templates on the CMS. Typically, where you place VersaTag in <body> section depends on whether you configure VersaTag for asynchronous or synchronous mode. For a more thorough explanation of the difference, see the section “What are the pros and cons of synchronous and asynchronous tags?”
Also, if external parameters need to be passed into VersaTag, for use by one of the contained conversion, retargeting or 3rd party tags, you will want to also insert code to pull and process any of this external page data prior to invoking VersaTag. VersaTag and its supporting code should be deployed to all your website’s pages. The agency should provide a comprehensive list of custom parameters that they intend to use to the Sizmek account manager so that they are able to configure VersaTag to accept them.
For marketers: when passing these parameters to your Sizmek account manager, please provide the following information:
• Parameter Name
• Type (Is it an Activity/Conversion Parameter, Retargeting Parameter or Conditional Parameter – for more info on parameter types, please refer to the section “What is the structure of the VersaTag code?”
• Desired order of the parameters (the order that you provide your account manager should be the same as the order you pass them into VersaTag)
• Parameter’s datatype – is it a number, date or string
3. Review VersaTag administrative and tagging procedures. Set up VersaTag’s user permissions. Review and formalize a procedure with your media agency on how you want them to notify you if they need new tags introduced. You will want to especially discuss any new 3rd party tags and assess its potential impact on page load performance.
4. Create mapping rules. You and your agency set up mapping rules to map one or more web pages to their corresponding Conversion or Retargeting tags. To simplify the mapping process, VersaTag gives you the flexibility to group related pages together with wildcards, or import them into the system with Excel.
5. Test VersaTag Mapping. Once VersaTag has been deployed on the site, you can use VersaTag’s debug and auditing tool to test the reliability of the mapping or tag deployment while navigating the site.
6. Migrate existing tags from site into VersaTag. Once VersaTag is set up, you will want to migrate all your site’s old tags into VersaTag’s container. This is important so that these tags aren’t called twice in error. To facilitate this migration process, VersaTag includes a comprehensive mapping report, which allows you to track and audit the progress of your migration.
Page 4
What is the structure of the VersaTag code?
The generated code for a typical VersaTag looks like the following:
Line Code Explanation1 <script>2 var versaTag = {};3 versaTag.id = “584” Identifies which VersaTag is firing4 versaTag.sync = 0 Is request handled asynchronously (0) or in sync (1) with pageload5 versaTag.dispType = “js” Type of response to return from our bursting server (JavaScript or
iFrame)6 versaTag.ptcl = “HTTP” How VersaTag request will be handled: secure (HTTPS) or
unsecure (HTTP)7 versaTag.bsUrl = “bs.serving-sys.com/BurstingPipe” URL location of Sizmek’s bursting server8 //versaTag.mobile = 1 Configures VersaTag for mobile sites (1) or standard sites (0)911-13 versaTag.activityParams = {“ParamName1”:”ParamValue1”,
“ParamName2”:”ParamValue2”These rows allow the webmaster to assign values from the webpage to be passed to Sizmek at the time of conversion. Sizmek has 6 predefined parameters which can be displayed in our standard reports. The Sizmek Predefined parameters include “OrderID”:””, “Session”:””, “Value”:””, “productid”:””,”productinfo”:””,”Quantity”:””
14-15 //Custom parameters:};
Beyond the predefined data parameters, an agency may define additional data that needs to be passed from the site during a conversion. The syntax for custom parameters is the same as predefined parameters
17 versaTag.retargetParams = {}; The agency may want to retarget users that perform a particular action on the advertiser’s website. The syntax for this portion of parameters is “TagID1”:”ParamValue1”
19 versaTag.dynamicRetargetParams = {}; Primarily used for e-commerce sites with many products. To retarget properly, the webmaster will need to populate this value in VersaTag with a product ID or SKU. The syntax for this portion of parameters is “TagID1”:”ParamValue1”
21 versaTag.conditionalParams = {}; Primarily used for advanced cases where complex business logic is used to fire 3rd party tracking tags. The syntax for this portion of parameters is “CondParam1”:”ParamValue1”
23 <script id=”ebOneTagUrlId” src=”http://ds.serving-sys.com/SemiCachedScripts/ebOneTag.js”></script>
This is the executional portion of the VersaTag Javascript codeNote: For the secure version of VersaTag, src is “https://secure-ds.serving-sys.com/SemiCachedScripts/ebOneTag.js” Ensure protocol (line 6 on this table) matches.
25 <iframe src=”http://bs.serving-sys.com/BurstingPipe? This is the iFrame (or pixel) execution portion of the VersaTag code. It is used in situation where javascript is not supported, or in cases where the webmaster has indicated that they do NOT want Javascript code executing on their site
26-38 cn=ot&onetagid=1742&ns=1&activityValues=$$Value=[Value]&OrderID=[OrderID]&ProductID=[ProductID]&ProductInfo=[ProductInfo]&Quantity=[Quantity]&$$&retargetingValues=$$&dynamicRetargetingValues=$$&acp=$$$$&”style=”display:none;width:0px;height:0px”>
Settings for the iFrame portion of the VersaTag code.
What is the structure of the VersaTag code?
The generated code for a typical VersaTag looks like the following:
Line Code Explanation1 <script>2 var versaTag = {};3 versaTag.id = “584” Identifies which VersaTag is firing4 versaTag.sync = 0 Is request handled asynchronously (0) or in sync (1) with pageload5 versaTag.dispType = “js” Type of response to return from our bursting server (JavaScript or
iFrame)6 versaTag.ptcl = “HTTP” How VersaTag request will be handled: secure (HTTPS) or
unsecure (HTTP)7 versaTag.bsUrl = “bs.serving-sys.com/BurstingPipe” URL location of Sizmek’s bursting server8 //versaTag.mobile = 1 Configures VersaTag for mobile sites (1) or standard sites (0)911-13 versaTag.activityParams = {“ParamName1”:”ParamValue1”,
“ParamName2”:”ParamValue2”These rows allow the webmaster to assign values from the webpage to be passed to Sizmek at the time of conversion. Sizmek has 6 predefined parameters which can be displayed in our standard reports. The Sizmek Predefined parameters include “OrderID”:””, “Session”:””, “Value”:””, “productid”:””,”productinfo”:””,”Quantity”:””
14-15 //Custom parameters:};
Beyond the predefined data parameters, an agency may define additional data that needs to be passed from the site during a conversion. The syntax for custom parameters is the same as predefined parameters
17 versaTag.retargetParams = {}; The agency may want to retarget users that perform a particular action on the advertiser’s website. The syntax for this portion of parameters is “TagID1”:”ParamValue1”
19 versaTag.dynamicRetargetParams = {}; Primarily used for e-commerce sites with many products. To retarget properly, the webmaster will need to populate this value in VersaTag with a product ID or SKU. The syntax for this portion of parameters is “TagID1”:”ParamValue1”
21 versaTag.conditionalParams = {}; Primarily used for advanced cases where complex business logic is used to fire 3rd party tracking tags. The syntax for this portion of parameters is “CondParam1”:”ParamValue1”
23 <script id=”ebOneTagUrlId” src=”http://ds.serving-sys.com/SemiCachedScripts/ebOneTag.js”></script>
This is the executional portion of the VersaTag Javascript codeNote: For the secure version of VersaTag, src is “https://secure-ds.serving-sys.com/SemiCachedScripts/ebOneTag.js” Ensure protocol (line 6 on this table) matches.
25 <iframe src=”http://bs.serving-sys.com/BurstingPipe? This is the iFrame (or pixel) execution portion of the VersaTag code. It is used in situation where javascript is not supported, or in cases where the webmaster has indicated that they do NOT want Javascript code executing on their site
26-38 cn=ot&onetagid=1742&ns=1&activityValues=$$Value=[Value]&OrderID=[OrderID]&ProductID=[ProductID]&ProductInfo=[ProductInfo]&Quantity=[Quantity]&$$&retargetingValues=$$&dynamicRetargetingValues=$$&acp=$$$$&”style=”display:none;width:0px;height:0px”>
Settings for the iFrame portion of the VersaTag code.
Page 5
There are five sets of variable arrays:
1. The VersaTag.activityParams array contains a list of optional parameters that would be passed directly into any of the Sizmek conversion tags contained within the VersaTag. Note that if the Conversion tag contains any 3rd party tags that require variables to be passed in, then these variables will be passed into the Conversion Tags through activityParams first, before being fed into the 3rd party tag using macros
Note that if a VersaTag contains Sales Conversion Tags, then the standard parameters of a Sales Conversion Tag will be auto-generated in the VersaTag tagging code. The parameters will then be passed into the Sales Conversion Tag being fired on a particular page.
Example: /Predefined parameters: “ OrderID “:””,”Session”:””,”Value”:””,”ProductID”:””,”Productnfo”:””,”Quantity”:””,
Parameter Description ExampleOrderID Dynamically set to reflect the order ID for the transaction. May be a string “OrderID”:”1234-5678-90”,Value Dynamically set to reflect the value currently stored within the user’s shopping cart. The
parameter should be a decimal number. If there are multiple products in the basket, this should be the Total price of all products in the basket.
“Value”:”229.88”,
ProductID Dynamically set to reflect the product ID/s. The Product ID parameter should be a string with the max length of 36 characters. Multiple product IDs can be added to the string separated by a delimiter e.g. a pipe (|)
“productid”:” ax-34579-989”,
ProductInfo Dynamically set to reflect product info. The Product Info parameter should be a string with the max length of 100 characters. Multiple items can be added to the string separated by a delimiter e.g. a pipe (|)
"productinfo":"Colour blue size XL",
Quantity Dynamically set to reflect the number of items currently stored within the user’s shopping cart. The parameter should be an integer. If there are multiple products in the basket, this should be the Total quantity of products in the basket.
Quantity”:”2”,
Session Dynamically set to reflect a unique user session id. This variable is optional and only required for conversions set to a session frequency. Each session id lasts until the users browser is closed.
“Session”:”123”,)
2. The Custom Parameters array contains a list of optional parameters used to provide additional information about a conversion activity. For example, an auto site may allow users to configure a car to their liking (model, trim, color, accessories). The agency may wish to leverage this custom information to target customized advertising to that user. The model, trim, color and accessory information would need to be pulled from the page and passed to the Custom Parameter portion of the VersaTag code.
Example: //Custom parameters: “model”:”Mazda6”,”trim”:”Sports”,”colour”:”red”,”accessories”:”none”}
3. The VersaTag.retargetParams array contains a list of optional parameters that would be passed directly into one of Sizmek’s static retargeting tags with values contained within the VersaTag.
Note that parameters for Sizmek dynamic retargeting tags are not passed through this array – this array is only meant for static retargeting tag. If you’re not sure of what type of Sizmek retargeting tags you are using, please consult your media agency or Sizmek account manager. You can also read the section below around “How should I set up Sizmek dynamic retargeting tags within VersaTag?”
4. The VersaTag.dynamicRetargetParams is slightly different than the retargetParams. The static retargeting tags have their values predefined. Dynamic retargeting pulls the value from the site in real time. Dynamic retargeting is used when an advertiser has a large number of products/offers which the agency wants to incorporate into highly targeted creative messages in their ads.
Page 6
Example: //Dynamic retargeting tags parameters. Syntax: “TagID1”:”ParamValue1”, “TagID2”:”ParamValue2”. ParamValue can be empty. versaTag.dynamicRetargetParams = {“67890”:”SKU12345”};
5. The VersaTag.conditionalParams array contain a list of optional parameters that would be used to feed conditional logic that determines whether or not a particular 3rd party tag or mapping rule should fire.
IMPORTANT - Please note:
• All parameters should be passed into the relevant code section (activity, retargeting or conditional) as communicated by the agency to the Sizmek account manager.
• Ensure you use a number for a parameter if the condition is based on a ‘range’ of values. A string can be added for anything else. String values can also contain wildcards.
• The order within each code section does not need to match up with the order of conditions as they appear in the platform.
What are the pros and cons of synchronous and asynchronous tags?
Sync mode refers to whether the page should wait until VersaTag responds before continuing to load. When VersaTag is in synchronous mode, then the web page waits until VersaTag responds before proceeding. The web page then has to wait until all relevant conversion; retargeting and 3rd party tags within the VersaTag are executed before proceeding.
When VersaTag is in asynchronous mode, the web page does NOT wait for a response, and simply proceeds with the rest of the page load, whether or not it hears back from the VersaTag server
The diagram below illustrates the differences in the order of events between synchronous and asynchronous modes:
Figure 1. Differences in sequence of events between asynchronous and synchronous modes
User accesses webpage User accesses webpage
Website executes VersaTag code
VersaTag server responds
Tags within VersaTag fire
Tags within VersaTag fire
3rd party tags execute
Web page content loads
Web page content loads
Action occurs on the website Web page content loads
Web page content loads
Synchronous(placed at end of <body>)
Asynchronous(placed at start of <body>)
Websiteexecutes
VersaTag code
VersaTagserver responds
VersaTagserver responds
VersaTagserver responds
3rd party tagsexecute
Webpage
contentloads
Tim
e
Page 7
Asynchronous VersaTags have a minimal impact on site performance since they are executed in parallel with the site’s page load. In general, this should be your preferred mode.
Synchronous VersaTags, on the other hand, are not executed in parallel with the loading of the page; rather, after the page passes control to VersaTag, VersaTag fires all their relevant tags before returning control to the page. However, since synchronous tags are often placed at the bottom of the <body> section so as not to interfere with page loads, there is a greater likelihood that the user navigates away from the page before all contained tags are able to fire, leading to some data loss.
Where in the <body> section should I place the VersaTag code?
This depends on two factors
• Are you running synchronous or asynchronous tags?
• Does the VersaTag rely on page-level variables?
The first question is important because it determines whether page-load time will be impacted by VersaTag. Though we can guarantee that Sizmek conversion and retargeting tags should have relatively insignificant processing time, and thus not impact load times significantly, there is no guarantee that various 3rd party tags that you may apply to VersaTag will process in an acceptable timeframe.
The second question is important because if VersaTag relies on page-level variables, the surest guarantee that those page-level variables are fully loaded and calculated before passing them to VersaTag is if the VersaTag code is placed towards the bottom of the page.
We’ve provided a flowchart that you can apply to help you make your decision:
Figure 2: Flowchart for determining VersaTag synchronicity settings
Which is abigger concern: page load timeor ensuring all
tags fit?
DoesVersaTag
rely on page-level data?
Place synchronousVersaTage code near the
top of the <body>section of theCMS template
Place synchronousVersaTage code near the
bottom of the <body>section of theCMS template
No Yes
Both
All tags fire Page-load time
Place synchronousVersaTage code near the
top of the <body>section of theCMS template
Place synchronousVersaTage code near the
top of the <body>section of theCMS template
Code for setting Activity
Parameters
Page 8
How does VersaTag handle URL Query Strings?
Some websites are designed to utilize query string at the end of URLs, as illustrated here.
This is particularly common in system-generated web pages, such as the Internal Search Results, or the Product Catalog pages.
The values in the query string could actually represent a true unique page, but it can also contain some computer-generated random variable that should be ignored, such as account ids or cache-busters. VersaTag lets you configure your mapping rules to conform to one of the two cases as needed.
VersaTag allows you to specify in your mapping rules, whether or not parameters at the end of a URL should be treated as distinct pages or not.
What are VersaTag API Calls?
In the next sections, we’ll look at utilizing VersaTag’s API calls to firing VersaTag on:
• Virtual Pages
• Flash Pages
• On-page event (e.g. Buttons)
GenerateRequest
The generateRequest method allows the web master to specify a ‘fake URL’ which can be used for mapping within the VersaTag UI instead of the actual page URL.
Syntax:
<script type=”text/JavaScript”>versaTagObj.generateRequest(“fakeURL”);</script>
Things to note:
• The fakeURL must include a http or https depending on the protocol of the page.
• The full VersaTag code should be placed on the page before the generateRequest code is added. This ensures that the versaTag objet exists before using the generateRequest method.
Get, Clear and Set Activity Parameter Values
A web master can also use the VersaTag API to get, clear and set activity parameters. This is discussed in more details in the ‘Advanced Scenarios’ provided in the following sections. Review these ‘advanced scenarios’ for the code syntax.
www.sizmek.com/platform/versatag?id=value&id=3523&cachebuster=3252351252
Domain: The physical server where your website is hostedURL: The indentifier which maps to the files on your serverQuery String: Part of a GET request to easily pass in values to customize output
*Note: URL stands for Uniform Resource Identifier
Domain URL Query String
Page 9
How does VersaTag handle Virtual Pages?
Basic Scenario
If you have sections of your website that generate new pages or dialogue boxes without explicitly changing URLs, and if you want VersaTag to recognize these virtual pages so that you can build mapping rules around them, then be reassured that VersaTag can easily handle all of these situations. The VersaTag API can be called to allow a virtual URL associated with an AJAX or Flash page to be kept within the VersaTag system
Virtual pages can sometimes be found in multi-page checkout processes of Retail and Travel e-commerce sites.
If you need VersaTag to register a virtual page, then you will need to insert the following code AFTER the main VersaTag script:
<script type=”text/JavaScript”>versaTagObj.generateRequest(“<Virtual Page Name>”);</script>
The <virtual Page Name> is a trigger which will send VersaTag a URL which can signal VersaTag to execute conversion or retargeting counting.
Example: below is the additional VersaTag code snippet for a virtual page for the 1st page of a checkout process on a site called retailSite.com
<script type=”text/JavaScript”>versaTagObj.generateRequest(“http://www.retailSite.com/checkout_page1.htm”);</script>
Note: that all calls to the VersaTag API can only be made AFTER the regular VersaTag tagging code has been executed for the page. When generateRequest is used, the URL of the Virtual Page MUST include a protocol (either http or https).
Advanced Scenario
The code above works for VersaTag calls that do not require any additional custom parameters passed into it.
If, on the other hand, the event needs to call a VersaTag which requires parameters passed into one of the contained Conversion, Retargeting, Dynamic Retargeting or 3rd Party tags/conditional logic, then the following code is required after the website event is triggered.
Page 10
Code forsetting
Retarget
Code for setting Activity
Parameters
Code forsetting
Dynamic
Code forsetting
Conditional
Note that you need to clear the parameter buffers before setting their value:
<script type=”text/JavaScript”>
// set activity parameter valueversaTagObj.clearActivityParam();versaTagObj.setActivityParam(“paramName”, “new parameter value”);
// set retarget parameter value
versaTagObj.clearRetargetParam();versaTagObj.setRetargetParam(“paramName”, “new parameter value”);
// set the dynamic retarget parameter value
versaTagObj.clearDynamicRetargetParam();versaTagObj.setDynamicRetargetParam(“paramName”, “new parameter value”);
// set conditional parameter value
versaTagObj.clearConditionalParam();versaTagObj.setConditionalParam(“paramName”, “new parameter value”);
// activate versa tag to generate a server call and handle the server response
versaTagObj.generateRequest(“http://www.site.com/checkout_page1.htm”)</script>
These API calls allow VersaTag to recognize the existence of virtual pages and can then be referenced in one of VersaTag’s mapping rules.
You can also retrieve the current values of the Activity, Retargeting, Dynamic Retargeting and Conditional parameters through the following API:
// get the activity parameter value the was just set actParamVal = versaTagObj.getActivityParam(“paramName”);
// get the retargeting parameter value the was just set retargParamVal = versaTagObj.getRetargetParam(“paramName”);
// get the retargeting parameter value the was just set dynamicRetargParamVal = versaTagObj.getDynamicRetargetParam(“paramName”);
// get the conditional parameter value the was just set conParamVal = versaTagObj.getConditionalParam(“paramName”);
Page 11
How does VersaTag handle Flash Pages and Events?
Basic Scenario
Pages in embedded Flash will require a slightly different mechanism. You would need to include this global JavaScript function that can be invoked anywhere within the Flash code:
functionrunGenerateRequest (FlashPageVirtualURL) {versaTagObj.generateRequest(FlashPageVirtualURL);}
When an event in Flash requires a call to VersaTag (e.g. when a Flash page is rendered), then the following function call should be triggered by that event to enable tracking of that Flash page:
if (ExternalInterface.available){ExternalInterface.call(“runGenerateRequest(<FlashPageVirtualURL>)”);}
The <FlashPageVirtualURL>should be a unique, full URL string that represents the virtual location of that particular Flash Page.
These API calls allow VersaTag to recognize the existence of pages and events within embedded Flash and can then be referenced in one of VersaTag’s mapping rules. As with OnPage events, the virtual URL used for FlashPageVirualURLs should be a fully formatted URL with protocol.
Example: An auto manufacturer (CarBrand) has a multi-step car configurator on their site which runs via Flash. To trigger a conversion when a user lands on step 1 of the configurator (pick model) the following functions would need to be added to the Flash file:
functionrunGenerateRequest (FlashPageVirtualURL) {versaTagObj.generateRequest(FlashPageVirtualURL);}
Associate with the step 1 page of the flash file:
{ExternalInterface.call(“runGenerateRequest(<http://www.carbrand.com/config/step1.htm>)”);}
Advanced Scenario
Setting parameters within Flash also follows a similar approach. The following global JavaScript function should be made available from any Flash page that needs to set parameter values:
<script>
// function runGenerateRequest() wraps versa tag generateRequest() API function// Please note that the URL passed into this function is a full URL (including ‘HTTP://’ ) and not a truncated URLfunction runGenerateRequest (url) { versaTagObj.generateRequest(url); }
// functions for setting the Activity Params to be accessed from Embedded Flash on a webpagefunction runClearActivityParam() { versaTagObj.clearActivityParam(); }function runSetActivityParam(paramName, paramValue) { versaTagObj.setActivityParam(paramName, paramValue) }
// functions for setting the Retargeting Params to be accessed from Embedded Flash on a webpagefunction runClearRetargetingParam() { versaTagObj.clearRetargetingParam(); }function runSetRetargetingParam(paramName, paramValue) { versaTagObj.setRetargetingParam(paramName, paramValue); }
ActivityParams
RetargetingParams
Page 12
// functions for setting the Dynamic Retargeting Params to be accessed from Embedded Flash on a webpagefunction runClearDynamicRetargetingParam() { versaTagObj.clearDynamicRetargetingParam(); }function runSetDynamicRetargetingParam(paramName, paramValue) {versaTagObj.setDynamicRetargetingParam(paramName, paramValue); }
// functions for setting the Conditional Params to be accessed from Embedded Flash on a webpagefunction runClearConditionalParam() { versaTagObj.clearConditionalParam(); }function runSetConditionalParam(paramName, paramValue) { versaTagObj.setConditionalParam(paramName, paramValue); }
</script>
These global JavaScript should be called directly from Flash whenever needed through an ExternalInterface call. Specifically, the calls would look like the following:
if (ExternalInterface.available) {
ExternalInterface.call(“runClearActivityParam”);ExternalInterface.call(“runSetActivityParam”,”activityParamName”, “activityParamValue”);
ExternalInterface.call(“runClearRetargetingParam”);ExternalInterface.call(“runSetRetargetingParam”,”retargetingParamName”, “retargetingParamValue”);
ExternalInterface.call(“runClearDynamicRetargetingParam”);ExternalInterface.call(“runSetDynamicRetargetingParam”,”dynamicRetargetingParamName”, “dynamicRetargetingParamValue”);
ExternalInterface.call(“runClearConditionalParam”);ExternalInterface.call(“runSetConditionalParam”,”conditionalParamValue”, “conditionalParamValue”);
ExternalInterface.call(“runGenerateRequest”,”http://www.blabla.com”); }
The runGenerateRequest call needs to be called after all the necessary activity, retargeting, dynamic retargeting and conditional parameters have been set
Note that all calls to the VersaTag API can only be made AFTER the regular VersaTag tagging code has been executed for the page.
How does VersaTag work with OnPage actions (buttons, forms)?
Since VersaTag associates conversion activity with a URL, we need to send VersaTag a URL when a user activates an on-page action.
Basic Scenario
The basic scenario describes a simple call to VersaTag through a button press or form submission. No parameters need to be set:
For each OnPage event , the webmaster will need to add the following code:
<script type=”text/javascript”> versaTagObj.generateRequest(“http://www.site.com/button1.htm”); </script>
For this case http://www.site.com/button1.htm is a URL designated by either the webmaster or the agency. It must be a fully formatted URL with protocol. Upon click, VersaTag will send this URL to the Sizmek server as a proxy for the OnPage action.
Dynamic Retargeting
Params
ConditionalParams
ActivityParams
RetargetingParams
Dynamic Retargeting
Params
ConditionalParams
Page 13
It is best to place the function in the onclick function of the button. Make sure the button’s type is “button” and not “submit”. However, changing the type to “button” will not submit the form, so in addtion, a code to actually submit the form will be added.
Example: A financial services company MyBank is using VersaTag. The agency wants to capture a conversion event when someone downloads a prospectus about a new savings product.
BEFORE
<form method=”post” action=”landingpage.html” name=”myForm” onsubmit=” versaTagObj.generateRequest(‘http://www.mybank.com/save360prospectus.htm’);”> <input type=”submit” value=”Send”></form>
AFTER
<form method=”post” action=”landingpage.html” name=”myForm”> <input type=”button” value=”Send” onclick=”versaTagObj.generateRequest(‘http://www.mybank.com/save360prospectus.htm’); document.forms[‘myForm’].submit();”></form>
In this example, the code to submit the form is, document.forms[‘myForm’].submit(); . Take note that “myForm” is the name of the form, so this is different every time.
Note that all calls to the VersaTag API can only be made AFTER the regular VersaTag tagging code has been executed for the page.
Advanced Scenario
The advanced scenario describes a call to VersaTag from a button click or form submission that requires parameters to be set. Let’s say you want to make a call to VersaTag when a button on your site is pressed. You can encapsulate the setting of parameters and the call to VersaTag within a function – the function is then called when that button is pressed
The function will:
• Collect the necessary data to be passed into VersaTag,
• Clear the relevant Parameter buffers – in the example below, it clears the Activity parameter buffer
• Sets the parameters – in the example below, it sets two activity parameters for your conversion tag, Product Name and Product Quantity.
• Generates the request to VersaTag, with the URL associated with the Button Press
//Function to be called on submit button clickfunction callVersatag(){
var productName = document.getElementById(“productName”).value; var productQuantity = document.getElementById(“productQuantity”).value; versaTagObj.clearActivityParam(); versaTagObj.setActivityParam(“ProductName”, productName); versaTagObj.setActivityParam(“ProductQuantity”, productQuantity); versaTagObj.generateRequest(“http://hosting.serving-sys.com/versatag/buttonSubmit/javascript/”);
}
This technique will also work for virtual pages where the URL does not change.
Your button code can then call the relevant function:
<form method=”post” action=”landingpage.html” name=”myForm”> <input type=”button” value=”Send” onclick=”callVersaTag(); document.forms[‘myForm’].submit();”></form>
Note that if the site event that you are attaching VersaTag to takes user outside of the Advertiser’s domain – for instance, a button that takes the user to the Advertiser’s Facebook page – then make sure you open the link in another browser window in order to ensure that the in-domain session remains open, and all tags within VersaTag can fire.
Page 14
Does VersaTag support organic or paid search?
Part of the data that VersaTag collects includes referral URLs. If the referring URL is a search engine or social portal, Sizmek can incorporate this information into our attribution and conversion tracking products.
Does VersaTag support Website analytics tags?
We do not recommend using VersaTag to hold tags from web analytics software, like OmnitureSitecatalyst or Google Analytics. VersaTag works well in conjunction with a Web Analytics tag.
How does VersaTag work with mobile devices that don’t allow cookies?
Mobile devices frequently do not allow the use of 3rd party cookies which can prevent many companies – including Sizmek – from collecting conversion and retargeting information from mobile devices. VersaTag can, however, record conversions to a unique identifier that is not based on cookies. Through our partnership with AdTruth, we use a probabilistic algorithm to determine a unique mobile device by analyzing over 200 attributes found on smartphones.
For VersaTag to properly capture mobile conversions, please make sure that the JavaScript version of the VersaTag code is implemented in the advertiser’s site. The <noscript> variation of the VersaTag code will not work with AdTruth
How should VersaTag be deployed across multiple domains?
It is often easier to manage a different VersaTag for each domain that you manage. Note though that this strategy may lead you to create duplicative mapping rules, particularly if there are parallel structures across your different domains (for instance, parallel sites for different languages). Generally, we recommend different VersaTags when different domains are managed by a different webmaster.
However, it sometimes makes sense to have a single VersaTag across multiple domains, particularly if you maintain a series of microsites with a single VersaTag administrator, who prefers to manage all mappings from a single VersaTag interface.
Note that VersaTag also has settings that allow you to manage mapping rules to make them applicable across sub-domains. For instance, if you needed mysite.com/page1, de.mysite.com/page1, fr.mysite.com/page1 and uk.mysite.com/page1 to fire the same mapping rule, then you can simply create a single mapping rule containing the primary page, and configure the mapping rule to fire across all related sub-domains.
How can VersaTag work across different environments – for instance, a Staging and Production environment?
Work with the VersaTag administrator to discuss the structure of your different environments. If the structure of your website changes in a predictable way between the Staging and Production environments, then the VersaTag administrator can easily export mappings to an Excel file and use Excel to bulk update and redefine their mapping so they are now relevant to the production environment. The new mappings in the Excel file can then be imported back into the VersaTag system.
For instance, if your environment changes from www.mysite.stage.com to www.mysite.com, then this can be quickly and reliably transformed with an Excel search-and-replace.
Page 15
How can I effectively audit the migration of tags into VersaTag?
The Mapping Report allows you to quickly detect which VersaTag and non-VersaTag tags are running for each page on your site. If you wanted to see all tags running for a page, then you would enter the page name into the Mapping Report interface.
Make sure you check the “Show me tags that are physically placed on the website, and that are not connected to VersaTag” checkbox to see all non-VersaTag tags.
The resulting report will have separate tabs for Conversion, Retargeting and 3rd party tags.
For instance, the Conversion tab should look something like this.
The “Connected to VersaTag” column will indicate whether a tag is contained within a VersaTag or not.The Mapping report will also give you details around each of the parameters used by your legacy tags – assess which ones you will need to migrate over into the VersaTag implementation.
Page 16
Will VersaTag run on a site that is not Javascript enabled?
Yes, it should, but we generally don’t recommend using custom parameters with VersaTag on a site that does not allow Javascript. You will need to tag your site with the <noscript> section of the generated VersaTag code. This will fire VersaTag as a web beacon / 1x1 Pixel. Only standard sales conversion parameters such as Revenue, Order ID, Product ID, Product Info and Quantity will be accepted as arguments into the pixel.
Here is the <no script> portion of code:
<noscript>
<iframe src=”http://bs.serving-sys.com/BurstingPipe?cn=ot&onetagid=3&ns=1& ;activityValues=$$Value=[Revenue]&OrderID=[OrderID]& ProductID=[ProductID]& ProductInfo=[ProductInfo]&Quantity=[Quantity]$$” style=”display:none;width:0px;height:0px”></iframe>
</noscript>
The following is a description of what is happening inside this code:
• http://bs.serving-sys.com/BurstingPipe - this is the call to Sizmek’s server
• cn=ot This is a flag to our servers to let it know that this is a VersaTag call
• onetagid=3 Each VersaTag has a unique ID number. This tells us which VersaTag is on your site.
• ns=1 This is a flag to our servers that the browser does not support Javascript.
• activityValues These are the default parameters that can be collected during a sales conversion. This information is discussed in this guide on page 5.
If you are using 3rd party tags piggybacked on a container tag, please note that you are only limited to a single 3rd party tag per container tag. That 3rd party tag must also be in the form of a pixel since they are being executed in the non-Javascript enabled environment, and not in the Sizmek server.
If the agency has requested additional custom parameters be collected from a non-Javascript site, the code will have additional info in it. See the highlighted portion below:
<noscript>
<iframe src=”http://bs.serving-sys.com/BurstingPipe?cn=ot&onetagid=53&ns=1& activityValues=$$Value=[Revenue]&OrderID=[OrderID]&ProductID=[ProductID]& ProductInfo=[ProductInfo]&Quantity=[Quantity] & &activityValues=$$activity1=testActivityVal1&activity2 =testActivityVal2&activity3=testActivityVal3$$ retargetingValues=$$100=someStaticValue$$& dynamicRetargetingValues=$$478=someDynamicValue$$&acp=$$param1=val1¶m2=val2¶m3=val3$$& dynamicRetargetingValues=$$d-retarget1=testDRetargetVal1&d-retarget2=testDRetargetVal2$$
“style=”display:none;width:0px;height:0px”></iframe>
</noscript>
Can VersaTag access the DOM to define when tags will fire?
Not currently. To fire tags in conjunction with an on-page event, please refer to the section titled “How does VersaTag handle OnPage actions?”
Page 17
How do I use VersaTag with an embedded YouTube video?
Many advertisers re-use content posted on YouTube within their own website. These videos are accessed via an iFrame into which is an embedded Youtube URL.
The YouTube player iFrame API allows you to “listen” for a change of state – for example from stopped to play. If you wish to assign a conversion to the play of a YouTube video use the OnPlayerStageChange function found here (: https://developers.google.com/youtube/iframe_api_reference#addEventListener).
This use case also requires the “OnPage” code found on page 9 of this guide.
Here’s a completed example:
//youtube player setup, add event listener for state changefunction onYouTubeIframeAPIReady() { var player; player = new YT.Player(‘player’, { width: 1280, height: 720, videoId: ‘M7lc1UVf-VE’, events: { ‘onStateChange’: onPlayerStateChange,
} }); }
// state change listenerfunction onPlayerStateChange(event) { //if player changed to playing, fire versatagif(event.data == YT.PlayerState.PLAYING){ runGenerateRequest(“http://myversatagurl.com”);
Will VersaTag negatively impact my site performance?
In general, VersaTag executes very quickly – under 60 ms for up to 25 Sizmek conversion tags.
To further tune performance, VersaTag provides the option to run asynchronously, which does not impact page-load performance. Synchronous VersaTag executions may impact page performance, but only if a slow-running 3rd party tag is included in your deployment.
Is VersaTag private and secure?
Yes. VersaTag does not store any data inside it beyond page view counts for each mapping rule. No VersaTag data is stored in the Sizmek cookie, and only non-PII data for conversion reporting is collected by any Conversion tags within a VersaTag implementation. Data is not stored client-side.
All VersaTag execution methods can be encrypted in an HTTPS protocol, allowing you to protect any sensitive data from sniffers. In fact, you can even force VersaTag to always use the HTTPS protocol, regardless of the security policy of the parent page.
More information about Sizmek’s data security is available from your Sizmek representative.
Page 18
What should I do if I have a site with a mix of secure and unsecure pages?
The VersaTag code can be generated either to work via a secure protocol or an unsecure protocol. The default configuration is unsecured which will work for many types of advertiser sites.
If your site contains secure sections where VersaTag will operate, we recommend that you use the secure protocol configuration of VersaTag. If your site has both secure and unsecure sections, then you’ll need both versions of the VersaTag. You can use your assigned VersaTag ID for both secure or unsecure implementations.
• apply the unsecure version of your VersaTag ID to the content template for unsecure pages
• apply the secure version of your VersaTag ID to the content template for secure pages (e.g. checkout)
The differences between the unsecure and secure configurations of the VersaTag code are highlighted below.
<script>var versaTag = {};versaTag.id = “34”;versaTag.sync = 0;versaTag.dispType = “js”;versaTag.ptcl = “HTTPS”;versaTag.bsUrl = “bs.serving-sys.com/BurstingPipe”;//VersaTag activity parameters include all conversion parameters including custom parameters and Predefined parameters. Syntax: “ParamName1”:”ParamValue1”, “ParamName2”:”ParamValue2”. ParamValue can be empty.versaTag.activityParams = {//Predefined parameters:“OrderID”:””,”Session”:””,”Value”:””,”productid”:””,”productinfo”:””,”Quantity”:””,//Custom parameters:“Customparam1”:””,”Customparam2”:””,”Customparam3”:””};//Static retargeting tags parameters. Syntax: “TagID1”:”ParamValue1”, “TagID2”:”ParamValue2”. ParamValue can be empty.versaTag.retargetParams = {};//Dynamic retargeting tags parameters. Syntax: “TagID1”:”ParamValue1”, “TagID2”:”ParamValue2”. ParamValue can be empty.versaTag.dynamicRetargetParams = {};//Third party tags conditional parameters. Syntax: “CondParam1”:”ParamValue1”, “ CondParam2”:”ParamValue2”. ParamValue can be empty.versaTag.conditionalParams = {“Condparam1”:””,”Condparam2”:””};</script><script id=”ebOneTagUrlId” src=”https://secure-ds.serving-sys.com/SemiCachedScripts/ebOneTag.js”></script><noscript><iframe src=”https://bs.serving-sys.com/BurstingPipe?cn=ot&onetagid=34&ns=1&activityValues=$$Value=[Value]&OrderID=[OrderID]&Session=[Session]&ProductID=[ProductID]&ProductInfo=[ProductInfo]&Quantity=[Quantity]&Customparam1=&Customparam2=&Customparam3=&retargetingValues=$$$$&dynamicRetargetingValues=$$$$&acp=$$Condparam1=&Condparam2=$$&”style=”display:none;width:0px;height:0px”></iframe></noscript>
Note that any 3rd party tag that is called within VersaTag does not adhere to any of these Versatag security behaviors. They will use whatever security settings have been coded into the Sizmek platform.
Page 19
Can I place VersaTag into another Tag Management system?
Each Tag Management system is unique and may require customization of the VersaTag code to work within the constraints of another Tag Management system.
If you are using any of the following Tag Management systems and would like to incorporate VersaTag, please contact your Sizmek Client Service Manager: Google Tag Manager, BrightTag(Signal), Tealium, Ensighten, Qubit, .
There is no guarantee that VersaTag will be able to function within another tag management system, but we will make every effort to make it work.
How do I access the VersaTag test page?
During deployment, the Sizmek QA team typically needs to test conversion events on the advertiser’s site to make sure that a) the tag is properly firing and b) that all relevant parameters are being received. This is done by using the VersaTag test page, a pop-up window that shows tag information and firing status.
When the advertiser’s site is publicly available the Sizmek QA team can do this with no problems. In some cases, the advertiser has a staging environment protected behind a firewall which outside companies cannot access. In this case, Sizmek may need the webmaster to provide screenshots of the test page to our QA personnel.
• You can test if the tags are working correctly before the campaign launches as follows:
• If this is required, a Sizmek QA person will send a list of the URLs where testing is needed.
• Browse to http://bs.serving-sys.com/BurstingPipe/adServer.bs?cn=at, which is a page that lets you set your local machine to ‘testing’ mode. In this mode, when visiting a page that includes a VersaTag, a pop-up window will open, showing you the tags activated by the VersaTag and the data sent by the VersaTag tag to the Sizmek servers.
• Send a screenshot of each test page to our QA representative.
Note disable browser’s Popup blocker, otherwise the Test pop-up window will not fire.
