Intelligent Content Engine

e-Spirit AG

2019-02-12
Table of Contents

1. Introduction

The Intelligent Content Engine module provides FirstSpirit with numerous functions that allow editors to represent even the most complex use cases relating to A/B testing, real-time targeting, and personalization. Despite the complexity, you can take full advantage of the benefits of FirstSpirit via the cloud-based implementation, even at times of unpredictable load peaks: The Intelligent Content Engine does not place additional strain on your current hardware. Simple things remain simple and complex things become possible. Thanks to the integration into FirstSpirit, the highly dynamic system remains very easy to manage - even without in-depth knowledge of the system.

A sample project is supplied as an integral part of the FirstSpirit ICE module. It is based on the familiar Mithras Energy project and can be used as the basis for your own FirstSpirit ICE projects. Through use cases, this documentation provides an explanation of the functions supported by the module. The documentation is based on the sample project.

1.1. Architecture

The Intelligent Content Engine consists of two components that are integrated into the live system:

  • The module to be installed on the FirstSpirit Server
  • The Intelligent Content Engine that assumes control of the variants

FirstSpirit ICE does not currently support a separate QA or development system.

Architecture of the Intelligent Content Engine
Figure 1. Architecture of the Intelligent Content Engine


  1. The module deals with the integration of the Intelligent Content Engine in FirstSpirit. The variants themselves are not maintained within FirstSpirit, but in the Intelligent Content Engine instead.
  2. The Intelligent Content Engine is used to maintain and to control the variants.
  3. In contrast to ContentCreator, variants can be maintained directly in the live view of the website. A special editing view is not required. However, the editor must be logged into FirstSpirit ICE. This brings the editor even closer to what the customer experiences on the website.
  4. The main use cases for the Intelligent Content Engine module are A/B testing and real-time targeting. The data exchange necessary for control purposes takes place in real time and directly between the Intelligent Content Engine and the application running on the live system. Despite the dynamic nature of the use cases, it is not necessary to provide more powerful hardware.

All variants are maintained directly in FirstSpirit ICE and configured exclusively there. The FirstSpirit project itself only contains the references to the corresponding project in the Intelligent Content Engine.

Static content is maintained in FirstSpirit as usual and made available via a live system. Classic deployment processes can be used here. Once the static content has been delivered to the customer's browser, the dynamic content of FirstSpirit ICE is requested directly from there by the Intelligent Content Engine. For this interaction, adaptations must be made in the FirstSpirit templates.

1.2. Technical requirements

The Intelligent Content Engine module has the following technical requirements:

  • FirstSpirit (Isolated- or Legacy-Mode) starting version 2018-10
  • Java 8 or higher
  • At least one account for the Intelligent Content Engine

e-Spirit AG Technical Support will provide an account for the Intelligent Content Engine.

2. Installation and configuration

Various components must be installed and configured in order to use the functions supported by the FirstSpirit ICE module. The steps to be completed are described in the following sub-chapters.

2.1. Module installation

Use the IntelligentContentEngine-<version number>.fsm file supplied to add the module on the FirstSpirit Server. To install the module, open the ServerManager and select Server propertiesModules.

Module management in the server properties
Figure 2. Module management in the server properties


The main panel contains a list of modules installed on the FirstSpirit Server. After clicking Install, select the supplied ice-fsm-<version number>.fsm file and click Open to confirm your selection. After successful installation, an Intelligent Content Engine folder is added to the list and must be given All permissions.

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

2.2. Project import

A sample project is supplied as an integral part of the FirstSpirit ICE module. It must be installed on the FirstSpirit Server. To do this, open the import dialog in the ServerManager via the menu item ProjectImport and click the Local button to select the ice_demo.tar.gz file from your local data system. Then assign a project name and description and confirm the import with Yes. After successful installation, the project is added to the list in the main panel (see figure Imported project in the ServerManager).

Imported project in the ServerManager
Figure 3. Imported project in the ServerManager


2.3. Configuring the project component

A project-specific configuration is required in order to use the Intelligent Content Engine module. This is set up using the project component that is already added to the sample project supplied.

To configure the project component, open the ServerManager and select Project propertiesProject components. A list of all existing project components is displayed in the main panel. Select the entry FirstSpirit ICE Configuration and click Configure to open the associated dialog.

Configuration dialog for the project component
Figure 4. Configuration dialog for the project component


An empty site is initially generated when e-Spirit AG Technical Support sets up the account for the Intelligent Content Engine. In the context of FirstSpirit, this represents a project within the Intelligent Content Engine.

The Intelligent Content Engine can be accessed via the following URL: https://adm.firstspirit-ice.com.

Site ID

The ID for your site must be entered in the form field of the configuration dialog. You will find this under the SettingsGeneral Settings menu item in the FirstSpirit ICE interface. It is shown at the top of the site:

Site ID in FirstSpirit ICE
Figure 5. Site ID in FirstSpirit ICE


2.4. Presentation channel for Product Feeds

If you are maintaining product data in your FirstSpirit project and want to generate Product Recommendations, you must add a further XML channel in addition to the presentation channels that are already available for your project.

To do this, open Server and Project Configuration and select Project propertiesTemplate sets. Clicking Add opens a dialog that must be completed as follows:

Creating a presentation channel
Figure 6. Creating a presentation channel


This figure shows the presentation channel configuration for the sample project supplied. The values xml or cvs may also be used as target file extensions.

Then confirm the dialog with OK to finish adding the presentation channel.

The new presentation channel is now added to the list of available template sets. It has been activated automatically and is thus available in the project immediately.

The new presentation channel is used to generate a Product Feed.

3. Adaptations in the project

Once the various components have been installed and configured, a number of adaptations must be made in the project. These adaptations are described in the sub-chapters below.

3.1. Template adaptations

The Intelligent Content Engine requires some libraries in order to be used. The module installed previously provides these libraries. The libraries integrate FirstSpirit ICE in the FirstSpirit project and must therefore be referenced in the page template being used.

There are two ways of referencing:

includeIceLibraries
The standard method references the required libraries directly and incorporates them in the form of two HTML script tags. For this purpose, the following call must be added before the closing <head> tag in the HTML section of the page:
$CMS_VALUE(class("com.espirit.moddev.ice.extensions.Initializer").includeIceLibraries(#global))$
getDynamicLibraryUrl & getStaticLibraryUrl
Alternatively, the required libraries can be referenced by specifying their respective URLs. The module provides the following methods for doing this:
$CMS_VALUE(class("com.espirit.moddev.ice.extensions.Initializer").getDynamicLibraryUrl(#global))$
$CMS_VALUE(class("com.espirit.moddev.ice.extensions.Initializer").getStaticLibraryUrl(#global))$

3.2. Configuring the page context

A FirstSpirit project usually contains various page types, which must be communicated to the Intelligent Content Engine. This is done by means of what is known as the page context, which must be individually configured for every page used in the FirstSpirit project. The page context is already defined in the sample project on the basis of respective page template in question.

To enable the page context to be assigned, a JavaScript script with the following format must be integrated in the <head> section of the corresponding page:

<script>
   DY.recommendationContext = {type: 'HOMEPAGE'};
</script>

Here, the following values are permitted for the context:

Table 1. Possible values for the page context
Page typeNecessary attributesExample

Homepage

-

DY.recommendationContext = {type: 'HOMEPAGE'};

Category page / overview page for products

Complete product hierarchy,

formatted as list of strings

DY.recommendationContext = {type:'CATEGORY',

data: ['TOP_LEVEL_CAT', 'CHILD_CAT','GRANDCHILD_CAT']};

Product page

SKU (Product Unique Identifier),

formatted as string

DY.recommendationContext = {type:'PRODUCT', data: ['SKU123']};

Cart

SKUs (Product Unique Identifiers),

formatted as list of strings

DY.recommendationContext = {type:'CART', data: ['SKU123','SKU234']};

Other (the page is not one of the previous types)

-

DY.recommendationContext = {type: 'OTHER'};



The parameter SKU corresponds to the article number of a product that is to be displayed. Since it is unambiguous, it is suitable for use as an identifier and, accordingly, is used in a wide range of use cases.

To support several languages, it is possible to enter a lng parameter as well. The locale of the currently displayed language can be used for this (e.g., de_DE or en_GB). The precise format of the locale can be freely selected but it must match the values that were entered in the Product Feed.

Example:

<script>
   DY.recommendationContext = {type: 'HOMEPAGE', lng: 'en_GB'};
</script>

3.3. Product Feed (optional)

Data Feeds, as they are known, provide the option of making volumes of data from FirstSpirit (such as product information) available to the Intelligent Content Engine. They are used to generate recommendations on the website. As well as the Content Feed - which produces reading recommendations, for example - the Product Feed is required to make FirstSpirit ICE product data available for AI-supported Product Recommendations. In addition, it enables significantly enhanced analysis functions to be used on the website based on customer flow. An example of the process for creating a Product Feed is described in the following sub-chapters and can be reproduced with the sample project supplied.

If you do not wish to use a Product Feed, you can skip this section.

To use the Product Feed effectively, it is essential that the page context for the individual product page is configured correctly. Make sure that you set the SKU for the product (DY.recommendationContext = {type:'PRODUCT', data: ['SKU123']};).

3.3.1. Generating the Product Feed on the FirstSpirit page

Product Feeds must be generated as CSV, XML, or JSON files and stored on the server so that they can be processed by the Intelligent Content Engine. Working on the basis of the sample project supplied, in which the JSON format is used, this chapter also uses this format to outline the process of generating a Product Feed.

The following code extract shows an example of this type of JSON file:

[
   {
      "sku": "1085",
      "name": "DS 1400 modular",
      "url": "http://mithrasenergy.com/content/Products/Thin-layer-modules/Thinlayer-Product_1085.html",
      "price": 123.45,
      "in_stock": true,
      "image_url": "http://mithrasenergy.com/.../thinlayermodules/thin-layer-solar-panel_900x600.jpg",
      "categories": "THIN_LAYER_MODULES",
      "group_id": "5"
   },
   {
      "sku": "1074",
      "name": "DS 1200 block",
      "url": "http://mithrasenergy.com/content/Products/Thin-layer-modules/Thinlayer-Product_1074.html",
      "price": 234.56,
      "in_stock": false,
      "image_url": "http://mithrasenergy.com/.../thinlayermodules/close-up-of-thin-layer-solar-panel2_900x600.jpg",
      "categories": "THIN_LAYER_MODULES",
      "group_id": "5"
   }
]

If external software is being used to maintain the product data, then this same software also has to be used for generating the file. If this is not the case, it is possible to use FirstSpirit for both maintaining the data and providing the file.

For this purpose, it makes sense to carry out persistence of the data in a data source. Using the presentation channel created during the installation process, the data can then be converted into JSON format.

The sample project supplied contains the mithras.products table template, whose JSON presentation channel is completed as follows:

JSON channel of the table template. 

$CMS_SET(product, {:})$                                                                 ❶
$CMS_SET(void, product.put("sku", ""+#row.id))$                                         ❷
$CMS_SET(void, product.put("name", tt_name))$
$CMS_SET(void, product.put("image_url", ref(tt_mainPicture, abs:1).url))$               ❸
$CMS_SET(void, product.put("price", tt_price))$
$CMS_SET(void, product.put("in_stock", true))$
$CMS_SET(groupId, "")$
$CMS_SET(categories, [])$                                                               ❹

$CMS_FOR(for_category,tt_categories)$
   $CMS_SET(void, categories.add(for_category.tt_name))$
   $CMS_SET(groupId, ""+for_category.fs_id)$
$CMS_END_FOR$

$CMS_SET(void, product.put("group_id", groupId))$
$CMS_SET(joiner, class("com.google.common.base.Joiner"))$
$CMS_SET(void, product.put("categories", joiner.on("|").join(categories)))$
$CMS_SET(productPageRef, "")$

$CMS_IF(groupId == "320")$
   $CMS_SET(productPageRef, "pageref:thinlayermodule_product")$
$CMS_ELSIF(groupId == "321")$
   $CMS_SET(productPageRef, "pageref:cristallinemodules_product")$
$CMS_ELSIF(groupId == "322")$
   $CMS_SET(productPageRef, "pageref:electricsupplyunits_product")$
$CMS_ELSIF(groupId == "323")$
   $CMS_SET(productPageRef, "pageref:solarenergystorage_product")$
$CMS_ELSIF(groupId == "324")$
   $CMS_SET(productPageRef, "pageref:powerinverter_product")$
$CMS_ELSIF(groupId == "325")$
   $CMS_SET(productPageRef, "pageref:additionalequipment_product")$
$CMS_END_IF$

$CMS_SET(void, product.put("url", ref(productPageRef, contentId: #row.fs_id, abs:1, templateSet: "html").url))$   ❺
$CMS_SET(void, jsonProducts.add(product))$   

The first step involves initializing the product variable as an empty map. The variable is used to generate a product that is transferred to the list of all the products in the final step.

The sku field is then defined. The corresponding dataset ID is assigned to this.

Both the URL for the product image as well as the URL for the product detail page must be rendered as an absolute URL. For this purpose, use the abs:1 parameter.

The next step involves completing the categories variable using the names and IDs of the categories that are selected in the form. The categories are each separated by a pipe symbol (|).

The generated product is then added to the jsonProducts list. The list is generated in the presentation channel of the corresponding page template.

In the sample project, the table template can be added to each page that is based on the product_feed page template. Its JSON presentation channel has the following content:

JSON channel of the page template. 

$CMS_TRIM(level:3)$
$CMS_SET(jsonProducts, [])$                 ❶
$CMS_VALUE(#global.page.body("products"))$  ❷
$CMS_VALUE(jsonProducts.toJSON)$            ❸
$CMS_END_TRIM$

The first step involves initializing the jsonProducts variable as an empty list that corresponds to the Product Feed being generated.

After that, the content section in which the table template is integrated is output. In the table template presentation channel, the jsonProducts list is completed using the individual items of product data.

Finally, the list that has been converted into JSON format is output.

Once the feed has been created, it is important to carry out an initial release and an initial deployment of the feed so that it can be read by the Intelligent Content Engine.

3.3.2. Integrating the Product Feed in the Intelligent Content Engine

When visiting the website, customers perform a variety of actions that make it possible to derive different types of information. Specific analyses are required in order to identify this information; these require the Product Feed to be used on the FirstSpirit ICE side. The Product Feed is continually updated as a result of regular retrievals and must therefore be accessible via the Internet. Specifying a URL in the following format makes it possible to restrict access to the Product Feed via HTTP Basic Auth: http://user:password@url

As a prerequisite for carrying out the necessary steps in the Intelligent Content Engine, the process of generating the Product Feed on the FirstSpirit side must be complete and the associated CSV, XML, or JSON file must be available on the server. Only then is it possible to perform integration on the FirstSpirit ICE side. To do this, open the FirstSpirit ICE management interface and select SettingsData Feeds to create a new Product Feed (click Add new).

Creating the Product Feed
Figure 7. Creating the Product Feed


In addition to the name (which can be anything you wish), the URL for the Product Feed file on the server must be specified as the Feed Source. Clicking on the Preview button verifies the accuracy of the settings. The settings can then be saved with the Save & Activate button. From this point on, the Product Feed is used for the page analysis and can be used without any further adaptations; for example, using the Audience Manager to segment customers based on the products they have viewed.

Product Feed settings
Figure 8. Product Feed settings


3.3.3. Events

The Intelligent Content Engine makes it possible to evaluate customer actions on the page in a way that is specific to target groups. This chapter outlines the Purchase event as an example. This event makes it possible to determine revenue for a particular target group or the average purchase value of an individual customer at the end of a payment process, for example.

The customer's actions cause predefined data to be transferred to the Intelligent Content Engine. In the case of the Purchase event, for example, the cart's total value, as well as the values of its individual items, can be transferred to FirstSpirit ICE.

DY.API('event', {
   name: 'Purchase',
   properties: {
      dyType: 'purchase-v1', ❶
      value: 90.55, ❷
      currency: 'any supported currency code', ❸
      cart: [

         {
            productId: 'item-34454', ❹
            quantity: 1,
            itemPrice: 65.87 ❺
         },
         {
            productId: 'sku-4324-bg',
            quantity: 2,
            itemPrice: 12.34
         }
      ]
   }
});

At this point, the event is identified as being a purchase.

The value variable specifies the cart's total value in the payable currency as a float value.

At this point, there is the option to specify an alternative currency that is different to the site default.

The productId variable contains the article number of the product. This must exactly match the sku value from the Product Feed.

The itemPrice variable corresponds to the item price for the product and is also a float value in the same way as the previously defined value variable.

Once customers have purchased products on the page, the resulting amount can be read on the dashboard. Evaluations such as the average value of the cart can also be retrieved (with a delay of one day).

Example dashboard in FirstSpirit ICE with optimization potential
Figure 9. Example dashboard in FirstSpirit ICE with optimization potential


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