RealtimeTargeting - Documentation

e-Spirit AG

Table of Contents

1. Introduction

The FirstSpirit RealtimeTargeting provides for the custom delivery of FirstSpirit content on websites to specific target groups and to individual website visitors. FirstSpirit makes it possible for each visitor to have the information corresponding to his or her needs provided at the right time on the suitable output device.

The result is that the information offered is more relevant to the website visitor. This leads to:

  • higher customer satisfaction,
  • long-term customer loyalty,
  • higher conversions, and
  • an optimized user experience.

The following conditions form the basis for website content delivery that is specific to the target group(s):

  1. Target group definition

    When implementing a project, the first thing is to define conceptually the target groups that are relevant to the specific website. This classification is always made on a case-by-case basis in each project and for each customer. The target groups are often also referred to as segments or (visitor) groups.

  2. Target group identification

    After defining the target groups, it is important to establish how to determine and identify which website visitors fall into which target group. The rules required for this depend significantly on the types of target groups.

    Here are a few examples:

    1. Mobile user vs. desktop user

      Since a visitor’s browser provides this information directly, the information is very easy to identify.

    2. Potential customer (guest) vs. existing customer

      This information can be determined in various ways with technology. For instance, it can be determined using a login area on the website.

    3. Potential customers interested in a particular topic

      The interests of a website visitor for a specific topic can be identified explicitly or implicitly.

      In the case of explicit assignment, the visitor is asked directly if a topic interests him or her. This information is stored in the visitor profile.

      Implicit assignment usually works with a "scoring" mechanism. This is used to establish what types of articles the visitor most frequently views. From a specific threshold, it is possible to assign the visitor to a target group.

    To identify the target groups, a profile for each website visitor is always required in order to have a lot of flexibility when creating target group rules.

  3. Maintaining the content for different target groups

    To begin with, the editorial maintenance of various content and assignment of this content to the different target groups (known as segments) provide the best experience for the website visitor. Both can be accomplished using the RealtimeTargeting module directly in the FirstSpirit user interface. In this case, FirstSpirit has to identify the list of defined segments in order to be able to provide the editor with the segments when maintaining the specific content.

  4. Delivery of content specific to target groups

    Delivering the appropriate content for website visitors always takes place in real time, since segment assignment can change for each page as required. The RealtimeTargeting module checks the following when delivering content:

    1. The segments to which the visitor is currently assigned
    2. The page content that is relevant to this segment

In addition to delivering content specific to target groups, the RealtimeTargeting module supports, for instance, the ability to cater to individuals by accessing individual profile data (volume of business in the last month, last login, etc.).

The technical details of the interplay of the described conditions are explained in the architecture overview presented in the next section.

1.1. Architecture overview

The architecture of the RealtimeTargeting module comprises four elements that interact with each other (see Figure Architecture):

The interaction of the individual elements is covered in more detail in the following sections.

Figure 1. Architecture

1.1.1. User Experience Pipeline

The User Experience Pipeline (UXP) runs every time a page is called by a website visitor. Its purpose is to analyze all of the target group information or segments that contain the current visitor. 1 to n Profiling & Segmentation Services are called for this purpose.

By default, the RealtimeTargeting module uses just such a service (Woopra™). If other or additional services are required, these can be added to UXP at any time for the project. The module at this location has a completely open architecture and is not limited to a specific service.

1.1.2. Profiling & Segmentation Service

This service handles three different tasks:

Visitor tracking and storing visitor profiles

Tracking logic on the website or in a mobile app is used to save all user interactions and to compile them into a profile. This persistent storage is used to provide a website visitor’s complete history. The history can in turn be used to define segments (see the point that follows).

Usually, in addition to standard activities (viewing a particular web page, downloading a specific file), project-specific events are transferred from the web page to the visitor profile (visitor purchased a specific product, order process was canceled by visitor, etc.).

Defining rules for segments

Based on the visitor profiles, rules can be used to define the segments to which the visitors are assigned. The Profiling & Segmentation Service typically has a graphical user interface for defining the rules. Creation and modification of rules can be done on a one-time basis when the project is set up as well as ad hoc at any time.

The service must be able to provide the list of all existing segments to FirstSpirit using the API so that it will be available to the editors for allocation of content.

Real-time delivery of a visitor’s segments
A key task of the Profiling & Segmentation Service is to provide the segment list associated with an identified website visitor. This interface must be real-time capable so that there is no delay in the downstream website delivery. The website visitor is usually identified by an ID (e.g. a cookie).

The FirstSpirit RealtimeTargeting module supports the connection to the Woopra™ service by default ( Woopra™ offers the three interfaces shown and contains turnkey implementations ready for use. Woopra™ also features turnkey CRM system integration (, offering additional useful application scenarios.

However, as previously mentioned, other services can also be implemented as an alternative.

1.1.3. Content creation and assignment in FirstSpirit

The task of the editors is to create specific content geared toward communication with target groups. For this purpose, a generally applicable version of content is usually created first and then a specific variant is developed which is built upon this version. This type of variant is then assigned to one or more target groups or segments.

A web page thus contains (from a physical perspective) all content variants. At the time of delivery, however, only the relevant content is provided (see section Content delivery).

1.1.4. Content delivery

After analyzing the segment list associated with a visitor, the web server run-time environment can filter and output the "relevant" web page content. Only the correct variants as determined by editor parameterization are displayed. Irrelevant content is not delivered.

Technically speaking, a Java Tag Library is used for this purpose. It compares the segments analyzed in the UXP with the editor’s page configuration and supplies the relevant content.

1.2. Technical requirements

The RealtimeTargeting module has the following technical requirements:

  • FirstSpirit (Isolated- or Legacy-Mode) starting version 2018-08
  • Run-time environment: Tomcat 7 (or web server with a servlet engine, version 3.0 or higher, and JSTL version 1.0 or higher)
  • Use of Profiling & Segmentation Service: Woopra™
  • JavaScript library: jQuery 1.9.1 (or higher)
  • Java 1.8 (or higher)

RealtimeTargeting uses the Java Architecture for XML Binding (JAXB) and the JavaBeans Activation Framework (JAF). Both are no longer part of the Java SE Platform since Java 9. If the FirstSpirit-Server is running on Java 9 or higher, JAXB must be added. The JAF must be installed on the FirstSpirit-Server as of version 2018-09. For this purpose the delivery contains the modules jaxb-fs-library-2.3.0.fsm and jaf-fs-library-1.2.0.fsm, which make the JAXB and the JAF known serverwide.

The RealtimeTargeting module actively supports only Tomcat 7 and 8 as the run-time environment at this time. It is tested with Tomcat 8. Use of other web servers has not been tested and is therefore not guaranteed to work.

By default, the RealtimeTargeting module uses the Woopra™ service previously mentioned. However, if the use of other or additional services is desired, these services can be added to a specific UXP project at any time. Chapter Additions describes the steps required to add these services.

1.3. Data protection and privacy

As previously described in the introduction, the RealtimeTargeting module supports delivery of specific website content. The visitors are assigned to predefined target groups based on their interactions with the website.

We expressly inform that for target group identification personal data is collected, used and transmitted to the Profiling & Segmentation Service.

The Woopra™ standard tracking mechanism collects the following data:

  • Browser type, domain name and IP address
  • End device ID and operating system
  • Referrer as well as the visitor’s time of access and total time spent on the site
  • Web pages visited and links clicked
  • All transmitted data

In addition, a cookie is used which is saved on the website visitor’s end device. The cookie uses a unique ID to identify the particular user and is valid for two years from the last website interaction.

These conditions are relevant to data protection and privacy laws and must therefore be addressed specifically for each project.

If additional information in the project is sent to Woopra™ or another Profiling & Segmentation Service is used, additions or adjustments must be made to the mentioned list accordingly.

The RealtimeTargeting module only allows for the identification, analysis and use of the specific interests of the website visitors. Data protection and privacy must therefore be addressed specifically for each project.

1.4. Topics covered in this documentation

This document describes the functions of the real-time capture of website visitor behavior and covers the components required to do this as well as how to install and configure them:

Chapter 2: This chapter describes the components required.

Chapter 3: This chapter covers how to install and configure the components on the FirstSpirit Server.

Chapter 4: The adjustments that need to be made in your FirstSpirit projects are described in this chapter.

Chapter 5: This chapter provides a few application scenarios for using the RealtimeTargeting module.

Chapter 6: The steps for expanding the module or replacing the Profiling & Segmentation Service used are contained in this chapter.

Chapter 7: This tutorial describes the necessary steps to add the RealtimeTargeting module to an existing project.

2. Components

The FirstSpirit RealtimeTargeting module consists of various components:

The individual components are presented in the sections that follow.

2.1. FirstSpirit module

The RealtimeTargeting module is the component that needs to be installed on the FirstSpirit Server.

Using the functions provided by the module on the FirstSpirit Server, the segments defined within the Profiling & Segmentation Service are transferred to your FirstSpirit project and have to be provided to the editor there in order to allow for target group specific assignment of the project content. This assignment is evaluated automatically during output of the content.

In addition, a function for checking the assignment made is provided to the editors in the form of the Persona Simulator.

2.2. FirstSpirit components

The different FirstSpirit components act like a link between FirstSpirit and the Profiling & Segmentation Service used.

There are two project components: While the first component triggers the template import to your project, the account data of the Profiling & Segmentation Service is managed in the second component. With these, the module establishes a project-specific connection between the FirstSpirit Server and the service.

The web components control the output of target group specific content generated by the editors in the preview, in ContentCreator and on the website (also refer to section Persona Simulator).

In this way, the functions of the two systems are combined and put to their best use.

2.3. Persona Simulator

The Persona Simulator is used to provide the editors a function in the preview and in ContentCreator which allows them to take on a persona whose association with particular target groups is specifically defined. The editors can thus view a web page as seen by the specific target group(s) and can use this to check the appearance of the content variants they created. Without the Persona Simulator, the editors would only be able to view the general content and would only be able to perform the check on the live website.

The Persona Simulator is based on the Multi Perspective Preview (see Roadmap 2013-2017 and the FirstSpirit 5.1 release notes). This allows it to be seamlessly integrated into ContentCreator (see Figure Persona Simulator in ContentCreator).

Persona Simulator in ContentCreator
Figure 2. Persona Simulator in ContentCreator

In the SiteArchitect preview, a bar associated with the Persona Simulator has also been added that looks and functions like the ContentCreator bar (see Figure Persona Simulator in SiteArchitect). The editors can thus use the Persona Simulator in SiteArchitect as well.

Persona Simulator in SiteArchitect
Figure 3. Persona Simulator in SiteArchitect

2.4. Profiling & Segmentation Service: Woopra

Woopra™ is a service for real-time analysis of website visitor behavior. The Woopra user interface provides a variety of information for analyzing this behavior, which can also be expanded as needed.

In this way, different visitors can be detected and identified again upon subsequent visits. This provides the option to freely define and assign different target groups (called segments) to them within the service and to provide them with content specific to the target group(s) via FirstSpirit. The individual visitor receives the information relevant to him or her, which optimizes the personal user experience.

By default, the RealtimeTargeting module uses the Woopra™ service previously mentioned. However, if the use of other or additional services is desired, these services can be added to a specific UXP project at any time. Chapter Additions describes the steps required to add these services.

3. Installation and configuration

Various steps need to be taken before using RealtimeTargeting functions:

Configuring a proxy server is only necessary if it is used to access the Internet (refer to section Proxy support for more information).

3.1. Registering and configuring Woopra

Tracking a website visitor is done using a corresponding Profiling & Segmentation Service, which is used by FirstSpirit for the RealtimeTargeting function, but is not supplied by FirstSpirit.

To use the Woopra™ service, an account registered on the following site is required:

The website to be analyzed needs to be added to the subpage My AccountManage Projects. It will then appear in the list of added projects displayed on the page (see Figure Woopra(TM) - Manage Projects).

Woopra(TM) - Manage Projects
Figure 4. Woopra(TM) - Manage Projects

Clicking Dashboard opens the Dashboard where the current visitor count as well as additional information is compiled in an overview (see Figure Woopra(TM) – Dashboard).

Woopra(TM) – Dashboard
Figure 5. Woopra(TM) – Dashboard

The website visitors can be assigned to different segments. These segments can be freely defined using the Manage menu item at the bottom. A tracking code, which must be included in the page, is used to record visitor actions. If a visitor fulfills the conditions defined for the segment(s) based on his or her actions, the visitor is added automatically to the respective segment(s) (see Figure Woopra(TM) – Labels).

Woopra(TM) – Labels
Figure 6. Woopra(TM) – Labels

For more detailed information about Woopra™, please read the Woopra dokumentation.

Information on how to use an additional or different Profiling & Segmentation Service is available in chapter Replacing the Profiling & Segmentation Service as well as in the particular provider’s documentation.

3.2. Installing the module

The module needs to be added to the FirstSpirit Server using the rtt-fsm-<version number>.fsm file that was supplied with the software. To install the module, open the ServerManager and select Server propertiesModules.

Managing modules under Server properties
Figure 7. Managing modules under Server properties

The main panel contains a list of modules installed on the server. After clicking Install, select the supplied rtt-fsm-<version number>.fsm file and click Open to confirm your selection. After successful installation, a RealtimeTargeting folder is added to the list and must be given All permissions (see Figure Managing modules under Server properties).

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

Select RealtimeTargeting Woopra Segment Provider Service in this folder and open the server-wide Woopra settings by clicking Configure (see Figure Woopra settings).

Except for proxy server information, the other information shown in this dialog is already provided initially and just needs to be changed if required. If the module communicates with the Profiling & Segmentation Service via a proxy server, the server’s data needs to be entered here (refer also to section Proxy support).

Woopra settings
Figure 8. Woopra settings

Close Settings and Server properties after configuration by clicking OK at each screen.

More information about installing modules is available in the FirstSpirit documentation for administrators.

3.3. Configuring project components

To establish a connection between RealtimeTargeting Woopra Segment Provider Service contained within the module and Woopra™ and to import the required templates into your FirstSpirit project, two project components need to be added and configured. Open the ServerManager and select Project propertiesProject components (see Figure Projekt components).

Projekt components
Figure 9. Projekt components

A list of all project components is displayed in the main panel. After clicking Add, select RealtimeTargeting Project Configuration and then Woopra Project Configuration and click OK to confirm your selection. Both project components will then be added to the list in the main panel and will need to be configured.

Select one component at a time and click Configure to open the associated configuration dialog.

RealtimeTargeting Project Configuration

In the configuration dialog for RealtimeTargeting Project Configuration, a schema first needs to be selected before various templates can be imported using the Import templates button (see Figure RealtimeTargeting Project Configuration). The schema is required for the data source of the Personas (see section Persona Simulator).

RealtimeTargeting Project Configuration
Figure 10. RealtimeTargeting Project Configuration

Woopra Project Configuration

Access data for Woopra™ and the website to be analyzed needs to be added to the Woopra Project Configuration dialog (see Figure Woopra Project Configuration). The access data is used by the manufacturer’s module service so that a connection can be made between the FirstSpirit Server and Woopra™. The specified website must also be entered in Woopra™ (see section Registering and configuring Woopra).

Woopra Project Configuration
Figure 11. Woopra Project Configuration

3.4. Setting up the Persona Simulator

The Persona Simulator requires two modifications to the project settings:

3.4.1. Selecting the Persona preview parameters

To use the Persona Simulator in ContentCreator, the multi-perspective preview needs to be activated by selecting Preview parameters in the project options.

To do this, open the ServerManager and select Project propertiesOptions (see Figure Selecting preview parameters). Under Preview parameters, use the corresponding button to select the Persona Preview Parameter page template. This page template was already imported to the project automatically during configuration of the RealtimeTargeting Project Configuration project component (see section Configuring project components).