Documentation Webtrekk GmbH | Robert-Koch-Platz 4 | 10115 Berlin Webtrekk Support | [email protected] Teaser Tracking Plugin (v2)
Table of Contents
1 Disclaimer 3 1.1 Introduction 4
2 Technical Requirements 5 2.1 Browser Support 5
3 Creating Teaser Parameters 6
4 Configuring and Activating the Plugin 8 4.1 Tag Integration (Web) 8 4.2 JavaScript 10
5 Initializing the Teaser Elements 13
6 Best Practices 16 6.1 View Tracking with Dynamic Teaser Insertion 16 6.2 View Tracking 17 6.3 Customizing a Website Goal 18 6.4 Customizing the Engagement Page 18
12/13/2018 2/18 Teaser Tracking Plugin (v2)
1 Disclaimer
This manual is the intellectual property of Webtrekk GmbH. This includes the contents but also all images, tables, and drawings. Change or removal of copyright notices, registering mark or control numbers are not allowed. Any use not permitted by German copyright law requires the prior written consent of the respective author or creator. This applies in particular to reproduction, editing, translation, storage, processing or distribution of contents in databases or other electronic media and systems.
Webtrekk GmbH allows the use of the content solely for the contractual purpose. It should be noted that the contents of this manual may be subject to changes, without that a reporting obligation on the part of Webtrekk GmbH can be derived from this. Users of this manual must independently obtain information themselves, whether modified versions or notes to the contents are present, for example on the Internet at https://docs.webtrekk.com/, and take these into account during operation.
All information provided in this manual is made available by Webtrekk GmbH. Webtrekk GmbH assumes no liability or warranty for errors or omissions in this manual, but avow for products and services according to the agreement which is expressly laid down for the respective products and services. The information contained in this manual result in no further liability.
Webtrekk GmbH Robert-Koch-Platz 4 10115 Berlin Germany
Phone +49 030 - 755 415 - 0 Fax +49 030 - 755 415 - 100 [email protected] www.webtrekk.com
12/13/2018 Teaser Tracking Plugin - Online 3/18 Teaser Tracking Plugin (v2)
1.1 Introduction
Teasers are image/ text elements that serve to attract attention and redirect your website visitors to a specific page or offer that you have defined. If you want to optimize teasers, you need more detailed information about the use of teasers. Not only which teaser elements were clicked on, but also which clicks led to orders, contact requests, etc. at the end.
With the teaser tracking plugin, you have the possibility of extensive analyses of your onsite teasers.
By integrating the plugin, teaser views and clicks are automatically captured on your website. If you specify additional parameters, you can also describe them in detail and evaluate them in combination with your web analytics data.
To evaluate the impact of a single teaser, in addition to views and clicks, engagement and conversion are calculated. The engagement measurement for a specific teaser is initiated as soon as it is clicked. For each page call that follows a teaser click, its engagement value is increased by 1. This happens until a website goal is reached or the user ends his visit to the website.
The display of all values recorded with the plugin is teaser accurate - either with aggregated daily values or in Webtrekk Live Analytics for the periods that can be set there. If you need other information, you can still enter it as your action parameters.
In the JavaScript file of the teaser tracking or Tag Integration, you can configure how many percents must be visible, and after how many milliseconds the request should be submitted.
This documentation describes the configuration and technical integration for using the teaser tracking plugin.
12/13/2018 Teaser Tracking Plugin - Online 4/18 Teaser Tracking Plugin (v2)
2 Technical Requirements
Please note the following technical requirements for a successful installation of the plugin:
The plugin only works with Webtrekk Tracking Pixel version 3.2.x or higher.
Required parameters have to be activated and configured (contact the Webtrekk support team if necessary).
Teaser elements must be initialized.
2.1 Browser Support
The teaser tracking plugin uses the "querySelector" method to search for the teasers to be measured. The following browsers support this method:
Internet Explorer from version 8
Microsoft Edge
Firefox from version 3.5
Google Chrome
Safari from version 3
Opera from version 10
12/13/2018 Teaser Tracking Plugin - Online 5/18 Teaser Tracking Plugin (v2)
3 Creating Teaser Parameters
The captured teaser information appears in Webtrekk as action parameters. You must first create these action parameters in Webtrekk Q3.
1. Log in to your Webtrekk Q3 account.
2. Go to Configuration > Custom Parameters.
3. Open the "Event parameter" tab. A list of all existing event parameters appears.
4. Click [Create new custom parameter]. You are forwarded to the specification dialog for custom parameters.
5. Make the following settings:
Parameter Description
Title Specify a title.
Description Enter a meaningful description of the parameter. This description is displayed when you call the help for this parameter.
Active Activate the parameter with the corresponding radio button.
12/13/2018 Teaser Tracking Plugin - Online 6/18 Teaser Tracking Plugin (v2)
Parameter Description
Preconfigured Select the required entry from the drop-down menu: Teaser - Placement (ID: 520) Teaser - Name (ID: 521) Teaser - Views (ID: 523) Teaser - Clicks (ID: 524) Teaser - Page Engagement (ID: 525) Teaser - Content (ID: 526) Teaser - Variant (ID: 527) Teaser - Conversion (ID: 528)
Parameter ID The ID is set automatically by the system.
Data type Select from the dropdown list the required data type: Figure This parameter is available as a metric. You can also select the figure type, see "Aggregation" below. Text This parameter is available as a dimension. The number of possible values is contractually agreed.
Generic This parameter is available as a dimension. Allows the unlimited storing of information.
Aggregation If you have selected the data type "Figure," you can also specify the figure type. Quantity: shows how often a parameter was tracked. Quantity and sum: a metric is generated that ads up the tracked values. Example A parameter is submitted twice, once with the value 5 and once with the value 3. "Quantity" is 2, "Sum" is 8.
12/13/2018 Teaser Tracking Plugin - Online 7/18 Teaser Tracking Plugin (v2)
Parameter Description
Amount You can specify the number of parameter values. This defines whether you parameter values pass single information or a range of information simultaneously. From the dropdown list, choose: Single value: A single information will be submitted Several values: Multiple values will be provided.
6. Click [Save] to save your settings. The event parameter is created and appears in the "Custom Parameters" overview.
4 Configuring and Activating the Plugin
The plugin is available in Tag Integration. Alternatively, you can integrate it in the standard pixel as a separate JavaScript file.
4.1 Tag Integration (Web)
Integrate the teaser tracking plugin into the container in which the webpage to be measured is located.
To add plugins the desired container, proceed as follows:
1. In the container overview, select the required container by clicking the corresponding entry.
2. Click [Add Plugin]. You will be forwarded to the overview of all available plugins.
12/13/2018 Teaser Tracking Plugin - Online 8/18 Teaser Tracking Plugin (v2)
3. Select the "Teaser tracking plugin" by clicking the appropriate button. The plugin configuration dialog opens.
4. Now enter the following information:
Parameter Description
Attribute name Mandatory. Specify the attribute name of the teaser element containing the teaser information (compatibility mode for teaser tracking version 1).
Delete teaser cookie Optional. Activate the checkbox to determine that the cookie in which after conversion the teaser information is stored will be deleted after a successful conversion.
Send engagement Optional. Activate the checkbox to specify that teaser engagements automatically are sent automatically.
When sending manually, you must define the variable "wt_teaserEngagements" on the desired pages.
12/13/2018 Teaser Tracking Plugin - Online 9/18 Teaser Tracking Plugin (v2)
Parameter Description
Additional conversion Optional. pages
Engagement pages Optional.
5. In the "Assign rules" area, you define the page areas on which the measurement is to be carried out.
6. Finally, click [Add plugin].
4.2 JavaScript
Since version 3.2.x of the Webtrekk tracking script, the use of plugins is supported. A plugin is all JavaScript functions that are transferred to the Webtrekk pixel.
For the integration of the teaser tracking plugin, you need the JavaScript file "pixel-teasertracking- v2.min.js."
1. Download the JavaScript file "pixel-teasertracking-v2.min.js" from the download area .
2. The configuration object "wt_teaserTrackingConfig_v2" is located inside the plugin. Make the following adjustment:
12/13/2018 Teaser Tracking Plugin - Online 10/18 Teaser Tracking Plugin (v2)
Example
window.wt_teaserTracking = function(conf) { if ((conf.mode === "page" || conf.mode === "config") && conf.requestCounter === 1) { var wt_teaserTrackingConfig_v2 = window.wt_teaserTrackingConfig_v2 || { teaserAttribute: "", viewPercent: 100, viewTime: 1000, attribution: "all", maxSendTeasers: { session: 10000, page: 1000 }, clearConversions: true, autoEngagements: true }; ...... } };
Parameter Description
teaserAttribute Specify the attribute name of the teaser element containing the teaser information (compatibility mode for teaser tracking version 1).
viewPercent Specify what percentage of the height and width of a teaser element should be visible in the user's viewport to recognize the teaser as "viewed." By default, teasers are sent if the HTML element is 100% visible in the user's viewport.
viewTime Specify how long a teaser element should be visible within the user viewport to recognize the teaser as "viewed." By default, teasers are sent when the HTML element is visible in the user's viewport for 1000 milliseconds.
attribution Select the attribution to be used for the conversion or website target: first: Only the first teaser associated with the conversion or website target. last: Only the last teaser associated with the conversion or website target. all: All teasers associated with the conversion or website target.
12/13/2018 Teaser Tracking Plugin - Online 11/18 Teaser Tracking Plugin (v2)
Parameter Description
maxSendTeasers Request limitation. session: Define a limit for sending teasers within the browser session. By default, a maximum of 10000 teasers is allowed during the browser session. To be able to capture all teasers within a browser session, enter the value "-1".
page: Define a limit for sending teasers on a single page. By default, a maximum of 1000 teasers is allowed on a single page. To capture all teasers on a single page, enter "-1".
clearConversions true = The cookie in which the teaser information is stored is deleted after a successful conversion.
autoEngagements true = Teaser engagements are sent automatically.
When sending manually, you must define the variable "wt_teaserEngagements" on the desired pages.
3. After you have adapted the Javascript file according to your requirements, insert the script before the "webtrekk_v4.min.js" in your HTML document.
Example
4. To activate the plugin functionality, the parameter "executePluginFunction" is used in the tracking pixel. You can make the setting either in the configuration variable (webtrekkConfig) or as a parameter of the pixel object.
Example Global Configuration
var webtrekkConfig = { trackId: "111111111111111", trackDomain: "track.webtrekk.net", domain: "www.website.com", executePluginFunction: "wt_teaserTracking" };
12/13/2018 Teaser Tracking Plugin - Online 12/18 Teaser Tracking Plugin (v2)
Example page-specific Configuration
var wt = new webtrekkV3(); wt.contentId = "de.startseite"; wt.executePluginFunction = "wt_teaserTracking"; wt.sendinfo();
A semicolon separates multiple plugins.
5 Initializing the Teaser Elements
To initialize the teaser elements, you need the object "wt_ttv2". You can mark the teaser elements to be measured by adding the configurations to the array "wt_ttv2."
The configuration for a teaser element is divided into "selector", "exclude", "data" and "conversion".
Example
window.wt_ttv2 = window.wt_ttv2 || []; window.wt_ttv2.push( { selector: "li.item:nth-of-type(2)", exclude: [ "li.item:nth-of-type(2) a:last-child" ], data: { name: "New Women Collection", rank: "Main Page Banner", content: "Women Collection", variant: "campaign" }, conversion: { type: "view", goal: "order", value: "10%" } } );
12/13/2018 Teaser Tracking Plugin - Online 13/18 Teaser Tracking Plugin (v2)
Parameter Description
selector Enter the teaser element to be measured.
You can either pass this directly as HTML element or pass the CSS selector of the element. Within the teaser element, all links, areas, buttons, and input fields of the type "submit" are marked for teaser click tracking.
exclude Define teaser links or teaser buttons for which no teaser click is to be measured. You can either pass them directly as HTML elements or you can pass the CSS selectors of the element.
data Specify the information of the teaser element using the following values:
Value Description
name Mandatory. Specify the teaser name.
rank Mandatory. Specify the teaser placement.
content Specify the teaser content.
variant Specify the teaser variant.
12/13/2018 Teaser Tracking Plugin - Online 14/18 Teaser Tracking Plugin (v2)
Parameter Description
conversion Specify how the teaser is to be assigned to the conversion or Web page target. You can set the following values:
Value Description
type Conversion type (default = product).
view: The teaser should be assigned to the conversion or website target as soon as it has been viewed.
click: The teaser should be assigned to the conversion or website target as soon as it is clicked.
product: The teaser should be assigned to the conversion or website target once it has been clicked and the teaser name matches the product name.
goal Conversion goal (default = both)
order: The teaser should only be sent during a conversion.
goal: The teaser should only be sent on a website target.
both: The teaser should be sent during a conversion or a website target.
value Conversion value (default = The teaser gets the same value as the product)
Percentage of the purchase order: The teaser gets a percentage of the purchase order value (for example, 5%).
Fixed value: The teaser gets a fixed value (for example, 15).
12/13/2018 Teaser Tracking Plugin - Online 15/18 Teaser Tracking Plugin (v2)
6 Best Practices
In this section we list some special applications in connection with teaser tracking, we offer you the corresponding implementation examples.
View Tracking with Dynamic Teaser Insertion
View Tracking
Customizing a Website Goal
Customizing the Engagement Page
6.1 View Tracking with Dynamic Teaser Insertion
Teasers whose visibility is dynamically controlled by the zIndex, a rotation of different teaser elements, or other means, must be additionally marked when they are displayed (whether or not they are in the visible monitor area).
Example
window.wt_ttv2 = window.wt_ttv2 || []; window.wt_ttv2.push( { selector: "li.item:nth-of-type(2)", exclude: [ "li.item:nth-of-type(2) a:last-child" ], data: { name: "New Women Collection", rank: "Main Page Banner", content: "Women Collection", variant: "campaign", seen: true }, conversion: { type: "view", goal: "order", value: "10%"
} } );
12/13/2018 Teaser Tracking Plugin - Online 16/18 Teaser Tracking Plugin (v2)
Parameter Description
seen The "seen" parameter is specified in the "data" configuration object. This controls the type recognition of the teaser during data acquisition. View tracking is then deactivated for this teaser. Click, engagement and conversion tracking will continue to work for this teaser.
6.2 View Tracking
The visibility of teasers that rotate on a page or whose visibility is controlled by the "zIndex" cannot be detected automatically. However, you can capture the views using manual view tracking.
If you use a "zIndex" to mark the teaser visibility, you must advise the plugin when a teaser is viewed. In this variant, the teaser is only marked for click, engagement and conversion tracking.
To measure the teaser views manually, call the following method and transfer the teaser information:
Example
window.wt_ttv2 = window.wt_ttv2 || []; window.wt_ttv2.push( [ "view", { name: "New Women Collection", rank: "Main Page Banner", content: "Women Collection", variant: "campaign", cType: "view", cGoal: "goal", cValue: "15" } ] );
Parameter Description
cType If you want to assign the teaser to the conversion or website target as soon as it has been viewed, also use the parameter "cType".
cGoal Via this parameter, you can also assign the seen teaser to a target.
12/13/2018 Teaser Tracking Plugin - Online 17/18 Teaser Tracking Plugin (v2)
Parameter Description
cValue Via this parameter, you can also assign the seen teaser to a value.
6.3 Customizing a Website Goal
With the variable "wt_teaserConversions" you can define further conversion targets in addition to your order confirmation page. On these pages, the variable "wt_teaserConversions" must be defined in the source code.
Set this variable directly on the conversion page, before the "webtrekk_v4.min.js" file.
Example Conversion Page
6.4 Customizing the Engagement Page
If you measure the engagements manually, you must define the variable "wt_teaserEngagements" in the source code of the desired engagement pages.
Set this variable directly on the desired engagement pages, even before the "webtrekk_v4.min.js" file.
Example Engagement Page
12/13/2018 Teaser Tracking Plugin - Online 18/18