e-Spirit AG

Table of Contents

1. Introduction

In the process of developing FirstSpirit, we constantly pursued a best-of-breed strategy, whose basic principle is using the best solutions for specific functions in every case. Logically, this means that it must be possible for third-party applications to integrate seamlessly into FirstSpirit.

The WebControlling module enhances FirstSpirit by including the analytical functionalities of the etracker web-controlling tool. This document describes the steps required to install and configure the module, explains the analysis capabilities of etracker, and shows how it is used from within FirstSpirit.

1.1. Range of functions

WebControlling provides editors with the following functions via etracker integration:

  • Checking visitor numbers for individual pages
  • Checking how often specific links are clicked on
  • Different viewing options for click frequency
  • Checking clicking behavior via click paths
  • Viewing all functions and statistics in the entire etracker suite

To integrate all these functions, etracker provides a dashboard and a scrollmap:

The etracker dashboard provides an overview of various statistics, which means that it displays information on a global level it does not provide page context.
Unlike the dashboard, the scrollmap refers to the page that is currently being shown. This means that its URL will always be transferred to the scrollmap.

1.2. Technical requirements

To use WebControlling, the following technical requirements must be met:

  • The latest versions of the WebControlling and AppConnect modules must be installed
  • FirstSpirit (isolated or legacy mode) 5.2.181007 or higher
  • At least one etracker Pro account

You can create the required etracker Pro account by filling in the relevant form on the etracker website. There are additional costs for using this type of account.

2. Installation and configuration

Various components need to be installed and configured in order to use the functions supported by the WebControlling module. The following sub-chapters describe the steps required to do this.

2.1. Installing the modules

The WebControlling delivery contains two modules that must be added to the FirstSpirit Server. To install the modules, open the ServerManager and select Server propertiesModules.

Module management in Server properties
Figure 1. Module management in Server properties

The main panel contains a list of all the modules installed on the FirstSpirit Server. Click Install, then select the AppConnect-<VERSION NUMBER>.fsm file provided first, followed by the WebControlling-<VERSION NUMBER>.fsm file. Each time you make a selection, click Open to confirm it. Once they have been successfully installed, the AppConnect and WebControlling folders are added to the list and both must be given All permissions.

The WebControlling module must also be configured. The steps decribing how to do this are in the next sub-chapter.

After any module installation or update, the FirstSpirit Server needs to be restarted.

2.1.1. Configuring the WebControlling Service

The WebControlling module makes it possible to log in to the scrollmap or the dashboard provided by etracker using single sign-on. To enable this, the AppConnect Connection which is deactivated by default needs to be activated in the WebControlling module service. The connection grants AppConnect access to the login details provided in WebControlling ProjectConfiguration.

To configure the service, open the ServerManager and select Server propertiesModules. Then expand the folder WebControlling for AppConnect and select the service in this folder.

WebControlling Service
Figure 2. WebControlling Service

Clicking the Configure button opens a dialog, which contains only a single slider that needs to be activated. Close the configuration dialog, Server properties, and ServerManager by clicking OK.

WebControlling Service  Configuration
Figure 3. WebControlling Service Configuration

Once configuration is complete, the service must be stopped and restarted.

2.2. Project components

A project-specific configuration is required in order to use WebControlling functions. It is set up using two project components, which must be added to the project in use. To add the project components, open the ServerManager and select Project propertiesProject components.

Project components
Figure 4. Project components

A list of all existing project components is displayed in the main panel. Click Add, then select WebControlling ProjectConfiguration and AppConnect ProjectConfiguration in turn. Click OK each time to confirm your selection. The project components will be added to the list in the main panel and will then need to be configured. The steps required to do this are described in the next sub-chapter.

2.2.1. Configuring project components

After project components have been installed, they need to be configured. To do this, open the ServerManager and select Project propertiesProject components. A list of all available project components is displayed in the main panel.

WebControlling ProjectConfiguration

Select WebControlling ProjectConfiguration in the list and click Configure to open the associated dialog.

Configuration dialog for WebControlling ProjectConfiguration
Figure 5. Configuration dialog for WebControlling ProjectConfiguration

The two mandatory fields in the dialog are for etracker login details, which the WebControlling module needs in order to link FirstSpirit with etracker. If the fields are left empty or the details are incorrect, a login page will be displayed when you try to call up the etracker dashboard or scrollmap. Enter your etracker login details and then click the OK button to close the dialog.

The etracker login details you provide will only be used if the AppConnect Connection is activated in the WebControlling Service and the WebControlling connector is selected in the AppConnect ProjectConfiguration configuration dialog described below.

AppConnect ProjectConfiguration

After completing the above steps for WebControlling ProjectConfiguration, select AppConnect ProjectConfiguration in the list of project components and click Configure to open the associated dialog.

Configuration dialog for AppConnect ProjectConfiguration
Figure 6. Configuration dialog for AppConnect ProjectConfiguration

The dialog has various configuration options for general settings and for using etracker in ContentCreator or SiteArchitect.

The Name, Symbol, and Url fields are mandatory fields. If any of these fields are left empty or the information entered is invalid, you will be alerted to this visually. If the name is missing, the button for WebControlling will be hidden in both clients. If the URL is invalid, the button will be shown but will remain inactive.


Depending on whether you would like to use the dashboard or the scrollmap provided by etracker, you will need to enter one of the following in this field:

  • etracker Dashboard
  • etracker Scrollmap
An image URL must be stored here. This image will be used as a symbol for the integration. The format must be bmp, gif, jpeg, jpg, or png and must not be larger than 25x25 pixels; otherwise, only an image detail will be shown. This is because FirstSpirit does not scale the symbol automatically.

While the symbol is visible in SiteArchitect as a button in the menu bar, it is only displayed in the Configure actions menu in ContentCreator.

Configure actions
Figure 7. Configure actions


The information you enter here also depends on which integration you require:

  • Dashboard: https://newapp.etracker.com/#/dashboard
  • Scrollmap: https://newapp.etracker.com/#/scrolldepth

In both clients, the URL is used to call up etracker.

The entries in the Name and Url fields must relate to the same integration.

The WebControlling connector must be selected here. It ensures that the connection between the WebControlling module and AppConnect is established, and enables you to access the dashboard or the scrollmap via single sign-on.

At the same time as the connector is selected, the AppConnect Connection must be activated in the WebControlling Service and you must have entered your etracker login details in the WebControlling ProjectConfiguration configuration dialog described above.


These sliders allow you to define the visibility of the button used to call up etracker in both clients. If visibility is deactivated for a client, this button will be hidden in that client and will no longer be available to the editors.

By default, visibility is activated for both clients.


Unlike SiteArchitect, which always displays the etracker page in the AppCenter, you can choose between two displays in the case of ContentCreator:

  • Dialog: The etracker page is displayed in a dialog within ContentCreator.
  • Browser tab: The etracker page is loaded in an additional tab in the browser.

By default, the dialog display is activated.

HTML Header

In this field, you need to enter the etracker Tracking Code, which can be found in the Account overview on the etracker page under the menu item SetupTracking Code.

etracker Tracking Code
Figure 8. etracker Tracking Code

If you would like to use the dashboard and scrollmap in parallel, the etracker Tracking Code must only be maintained for one of the two integration options. Otherwise, data entry problems will occur.

The available variables can be defined in this code as required. The following extract shows an example of how the page name is used.

etracker Tracking Code. 

<!-- Copyright (c) 2000-2018 etracker GmbH. All rights reserved. -->
<!-- This material may not be reproduced, displayed, modified or distributed -->
<!-- without the express prior written permission of the copyright holder. -->
<!-- etracker tracklet 4.1 -->
<script type="text/javascript">
   [#if pageref??]
	   var et_pagename = '${pageref.uid}';

<script id="_etLoader" type="text/javascript" charset="UTF-8" data-respect-dnt="true" data-secure-code="123456" src="//static.etracker.com/code/e.js"></script>
<!-- etracker tracklet 4.1 end -->

The field can also be used to enter code such as HTML, JavaScript, and style sheets, and you can add this code to any page template for the project in use. The field content can be integrated via a CMS VALUE expression, which must be added to the header of the page in use.

The Apache FreeMarker scripting language also allows you to enter complex expressions in this field. Furthermore, the module provides the webedit, preview, and pageref variables so that it can retrieve context-specific information.

2.3. Web component

The AppConnect module has a web component. This component provides the functions in ContentCreator, so it must be added to the project in use, but it does not need to be configured any further.

Open the ServerManager and select the ContentCreator tab in Project propertiesWeb components.

Web components
Figure 9. Web components

A list of all existing web components is displayed in the main panel. Click Add, then select AppConnect WebResources and click OK to confirm your selection. The web component is added to the list in the main panel (see figure Web components).

If there is no active web server, it must be activated. Select it in the selection list, and start the installation by clicking Install. After it has been successfully installed, activate the web server by clicking Activate.

If there is already an active web server, this simply needs to be updated by clicking Update.

Close Project properties and the ServerManager by clicking OK.

More detailed information on how to add web components is available in the FirstSpirit Documentation for Administrators.

2.4. Configuration on the etracker website

To compile the required statistics, etracker needs to be made aware of the URL for the project's live page. You can do this in the Account overview on the etracker page under the menu item AccountDomains for Web AnalyticsMain domain.

3. Template adaptations in the FirstSpirit project

While installing and configuring the various components, the fields that you need to complete include HTML Header in the configuration dialog for AppConnect ProjectConfiguration. You can use this field to enter the etracker Tracking Code and also insert HTML. To ensure the field content is applied, it must be integrated into the page in use. You can do this by placing the following CMS_VALUE expression before the closing <head> tag in the template you are using:


4. Use in FirstSpirit

The WebControlling module enables etracker to be seamlessly integrated into FirstSpirit. When the module is installed, its functions will be available in both clients. The following sub-chapters describe how it is used in each client.

If individual HTML is entered in the project component in addition to the etracker Tracking Code, it will be applied automatically to the appropriate page template.

4.1. SiteArchitect

The two integration options for etracker, which can be defined in the project component, are seamlessly integrated into the menu bar in SiteArchitect as additional buttons.

Menu bar in SiteArchitect
Figure 10. Menu bar in SiteArchitect

Click the button for the dashboard or scrollmap to open whichever one you wish in the AppCenter. Each integration opens in a separate tab. If one integration is already open in a tab, clicking on the button again will take you to that tab.

4.2. ContentCreator

The integration options that can be defined in the project component are provided in ContentCreator via the menu ActionsPlug-ins.

Actions menu
Figure 11. Actions menu

Depending on the configuration, the dashboard or scrollmap will open either in a dialog in ContentCreator or in a new browser tab. If registration was configured using single sign-on, you will be forwarded to the dashboard or scrollmap automatically. Otherwise, the etracker login page will open first and you will have to enter your account details manually.

Unlike the dashboard, which provides an overview of various statistics, the scrollmap always refers to the page that is currently being shown. For this reason, its URL will always be transferred to the scrollmap.

5. Legal notices

The WebControlling module is a product of e-Spirit AG, Dortmund, Germany.

Only a license agreed upon with e-Spirit AG is valid with respect to the user for using the module.

Details regarding any third-party software products in use but not created by e-Spirit AG, as well as the third-party licenses and, if applicable, update information can be found in the file wfa-license-info.html included with the module.

6. Disclaimer

This document is provided for information purposes only. e-Spirit may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. e-Spirit specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.