FirstSpirit ICE

e-Spirit AG

FirstSpirit Version 5.x

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.

2. Onboarding

2.1. Creating a New Site

Each FirstSpirit ICE account has one or more sections called Sites. Each site is designed to support a different domain or app, and is a discreet set of FirstSpirit ICE elements and settings.

To create a new site:
  1. If this is the first site in the account and you have not implemented FirstSpirit ICE via an eCommerce platform plugin, you can edit the ‘default site’ settings instead of creating a new one by going to Settings › General Settings and clicking the edit icon . If you want to create an additional site, continue with this procedure.
  2. Click the dropdown arrow on your cover photo at the top left of the screen.
  3. Click Add Site and complete the settings.

  4. Choose a name for your site
  5. Select the relevant platform; Web, iOS or Android (please note that Web includes also Mobile Web)
  6. Enter the site’s main URL (usually the site’s domain)
  7. When implementing FirstSpirit ICE via an eCommerce platform plugin, select the appropriate platform choice. 
  8. In the Localization section, select the currency which will be used in all FirstSpirit ICE revenue-based reports.
    • Currently over 40 different currencies are supported; see this article for the full list.
    • FirstSpirit ICE uses the exchange rate provided by the external service OAnda’s in order to convert all reported revenue into the selected currency above. The exchange rate is updated once a day at 4am (GMT), and is used for continuous conversion until the following day’s updated exchange rate
  9. Click Save. You will be directed to the General Settings page.

2.2. Page Context for Web

In order for FirstSpirit ICE’s script to deliver the right experiences for the different page types on your site, and for us to gather the accurate behavioral data, you are required to report the context of each page. The page context includes details about the page type (home page, product page, etc.) as well as page-specific information (product, category, etc). The page context should be placed in your header of each page, right before the FirstSpirit ICE script is called as specified below.

Important: Without page context data, many important FirstSpirit ICE features will not work. For details, see Missing Page Context Data.

Page Context for eCommerce Sites

The following calls should be placed before the FirstSpirit ICE script in the <head> tag of your site, as seen in the example below. Once this has been implemented in the <head> tag before the script and validated, please contact us to enable additional advanced features in your account.

<script type="text/javascript">
   // <![CDATA[
         window.DY = window.DY || {};
         DY.recommendationContext = {
            type: "PRODUCT",
            data: ['SKU123']
         }; // in this example - a product page
   // ]]>

Page Type Required Attributes Example
Category Full hierarchy of category names
Product Page SKU (formatted as a string)
Cart SKUs (formatted as a list of strings)
Other (if page matches none of the above page types)

For multi-locale support, please add the field “lng” with the relevant locale, for instance “en_GB”; the locale syntax can be determined freely, however it must match the column translations used in the Data Feed.

Context with locale example:

Page Context for Media (Content) Sites

The following calls should be placed before the FirstSpirit ICE script as seen in the example below:

<script type="text/javascript">
   // <![CDATA[
         window.DY = window.DY || {};
         DY.recommendationContext = {
            type: "POST",
            data: ['POST_ID123']
         }; // in this example - a post page
    // ]]>

Page Type Required Attributes Example
Category Full hierarchy of category names
Article Page Article ID

Important: If you are setting the page context based on URLs, make sure to set the identification to ignore URL parameters.

Multi-Language Support for Page Context

To indicate the language of a page, add the field lng (e.g. ‘en_GB’). This is only required for pages not using your default language. You can specify any string for this field, but it should match the column translations used in the Data Feed, as detailed here.

Example page context with language setting:

Missing Page Context Data

If you are not able to report the page context at all, many features will not be supported such as:

  • Social proof
  • Many audience conditions (affinity, context page visit, home page visit, etc.)
  • Recommendations

If you are able to report the page context, but cannot place it in the header, there is a chance that the page context will not be reported to our servers on time. The effect may vary for each pageview. In cases where the page context is not reported on time, the features listed above will not work. The page context may still be reported, but there are no guarantees and we would expect inconsistent results (It may work fine 100% of the time one day, but only 67% of the time the next).

3. General

3.1. Campaign Overview

A campaign – the framework that organizes and serves the content on your site – is comprised of various Experiences. Each experience can target different visitor segments as well as test (or automatically optimize) content variations. For example you can run a hero banner with a different experience for ‘tech enthusiasts’ and ‘gear lovers’ while testing different promotions for each.

Each experience has 2 main building blocks:

  1. Targeting: who should the experience be served to, where on your site, and at what time.
  2. Variations: what should be served  to the targeted visitors.

Targeting Experiences

Personalize an experience by targeting your audience. You can target visitors by different sets of conditions such as; past behavior (e.g., visitors who added items to the cart), technology (e.g., mobile users), traffic source (e.g, social networks), gender and time (e.g., weekend only). Only visitors who meet your set of targeting conditions will be served with the experience.

If a visitor meets the conditions for more than one targeted experience, the one with highest priority will be served. If a visitor doesn’t mean any of the conditions, the default experience will be served. Learn more about Targeting.

Experience Variations

A variation is what you will be serving your targeted visitors. Depending on the type of campaign module you chose, a variation is either a promotion served by a  Dynamic Content,  a JS code fired by a JavaScript Action , or an ad creative served by a Display ad. You can create a single variation or multiple variations to test and optimize your campaigns.

There are three ways of creating variations:

  • Create a new variations from scratch, select an out of the box template or a custom template built by your developer.
  • Use an existing variation by clicking on ‘copy from another experience’ button and then editing the copy to your needs.
  • Create variations using a Data Feed when you have a large number of variations and you would like to automate and sync their content by tying them up to a data source.

Learn more about creating Variations.

 Allocation Method

The allocation method determines how the variations are served to your targeted audience. There are two methods to choose from:

  • A/B test: manually assign,  to each variations and the Control Group the percentages of visitors to serve the variation to. Once enough data is collected, the system will declare a winning variation. It is up to you however, to decide whether to continue serving all running variations or pause/delete poorly performing variations.
  • Auto Allocate: allow the system to automatically shift traffic towards the best performing variation in real-time. You can choose to assign traffic to your control group and measure the uplift generated from the automatic allocation performance.

Learn more about Traffic Allocation and how to select the right method for your experiences.

Primary Metric

The primary metric is the experience’s objective and determines the success of your variations. For example, the objective of a newsletter signup overlay is to increase subscriptions. Purchase, revenue, and goals are available in your reports by default. however,  selecting the right primary metric has significance; In A/B test method, it will be the parameter to determines the winning variations. In the Auto-allocate method, traffic will adjust towards the variation that improves this metric.

The system provides the following Metics:

  • Click-Thought Rate (CTR)
  • Purchases
  • Purchase Revenue
  • [Custom] Goal Conversions
  • Unit CTR

Learn more about Primary Metrics.

 Experience Settings

Fine tune your experiences success parameters by clicking on the () icon:

  • A/B Test Options – Defines the Probability to Be Best score required for a variation to be declared as a winning variation, the minimum time required before a winner is declared and the recipient of the declaration notification email.
  • Advanced settings  – Defines the stickiness and the attribution window.

Learn more about Experience Advanced Settings.


3.2. Copying Campaigns Between Sites

If you have more than one site in your FirstSpirit ICE account, you can copy campaigns from one site to a similar one. For example, between a staging and live environment or between sites supporting different languages and locations.

About Copying Campaigns

Copying campaigns is designed to copy from sites that are very similar to each other. The source and target site must have the same platform type (website, Android, iOS) and vertical (ecommerce, media, etc.). If there are dependencies on other FirstSpirit ICE features such as Audiences, Goals, Evaluators, or any other entity, the copied campaign will search for an entity with the same name in the target site. If these do not exist in the target site, the copy will fail.

The campaigns are copied with all experiences, variations, labels, and other settings to the target site. Variations that are connected to templates are detached from the original templates, but maintain all configurations and settings.

You can determine if you want to publish your campaign on the target site, or save it as a draft.

Notes and Limitations
  • Copying campaigns is not supported for all campaign types such as Dynamic Links.
  • If one experience has a variation that is created using a variation feed, the campaign cannot be copied to a different site.
  • If you copy a campaign that is published, but also has a draft, only the published version is copied.
  • You cannot copy to a site that already contains a campaign with the same name.
  • If the campaign is dependent on another FirstSpirit ICE feature such as evaluators, audiences, strategies, or any other entity, the target site must have a parallel entity with the same name.

Copying a Campaign to Another Site

  1. Go to the list page that contains your campaign and click the  icon and select Copy To Another Site.

  2. Check the target site(s). Only target site that share the same vertical and platform as the current site are available.
  3. Specify if you want copied campaigns to be saved as drafts or published in the target site.
  4. Click Copy to Site.

3.3. Dashboard

The dashboard gives you a high-level overview of your campaigns, site performance, audiences, product updates, and more. You can adjust the time frames, or drill down by clicking entities throughout the dashboard.