jCustomer key concepts

November 14, 2023

Overview

jCustomer gathers information about users actions, information that is processed and stored by jCustomer services. The collected information can then be used to personalize content, derive insights on user behavior, categorize the profiles into segments along user-definable dimensions, or acted upon by algorithms.

The Oasis Context Server (CXS) specification

The interface between jExperience and jCustomer is defined by the OASIS Context Server specification. The specification is a work in progress at the OASIS foundation and defines an open standard to deliver personalized user experiences. The goal is to assist organizations that currently struggle to create and deliver consistent personalized experiences across channels, markets and systems. The specification defines a standardized API contract to talk to context server implementations.

The following image shows the two APIs that are described in the CXS specification. The CXS Public API is used to collect data and the CXS Internal API is used for Customer Data management, analytics, and configuration.

interface.png

Apache Unomi

jCustomer is a commercial version adding extensions on top of Apache Unomi.

jCustomer processes customer-generated events and executes rules based on events to update customer profiles. jCustomer stores and delivers the profile in a context object. The object also contains augmented information such as the profile’s resolved segments or properties aggregated from different systems connected to jCustomer, for example, from CRM and WCM applications.

jCustomer is an API-first server and is used by jExperience to track customers and deliver A/B testing and personalization. It can also be used to deliver ads or even to build personalized native mobile applications.

Both jCustomer and Apache Unomi products follow the same versioning scheme (jCustomer 1.5.7 is built on top of Apache Unomi 1.5.7). In some occurrences, this documentation will point to Apache Unomi documentation to avoid duplicating content.

Functional architecture

unomi.png

Events

Events are the main inputs into the jCustomer server. Events can range from a single page view event to a native mobile application action such as a button press or application start. New applications may define new event types and simply send them through the CXS Public REST API using HTTP POST calls to be processed and recorded by jCustomer.

Context

A context is a collection of the current customer profile and contextual information about the current interaction with jCustomer, for example the customer’s segments and session information (resolved geographic location from the IP).

Profiles

Profiles represent information collected about a customer. Profiles can contain extensible properties that may contain personal or anonymous data. By default, a cookie keeps track of a profile on the browser side. Also, no personal data is required by the tracking mechanism as a profile ID is automatically generated when a new visitor is detected by jCustomer.

Rules

Rules are composed of conditions and actions. If a rule’s conditions are satisfied, the actions defined in the rule are executed. You can define and modify rules at any time and rules will react to new events in the system. As conditions and actions can be extended using plugins, rules are a powerful way to add real-time functionality to jCustomer. The rule engine behaves as follows:

  1. An internal or external event is received by jExperience.
  2. The rule engine is triggered.
  3. Rules are evaluated in order of priority. For each rule, the rule engine evaluates rule conditions. If conditions meet the rule criteria, rule actions are executed in the order in which they are defined.

Conditions

Conditions are matched against events or profiles and are used to build segments or rules. For example, profiles with an age property above 21 or a profile that has viewed a page or a group of pages are both conditions. You can use AND and OR operators to build more complex conditions.

Actions

Actions are sections of logic that execute when a certain set of conditions is met. Actions only execute when the conditions of a rule are satisfied. jExperience contains the following predefined actions:

  • Update profile properties
  • Add to list
  • Send an email

Segments (Dynamic)

Segments group the profiles that are stored in jCustomer. A segment defines that conditions that a profile must match to be included in the segment. As segments are dynamic groups, a customer profile can move segments when customer information changes or when profile conditions are modified.

Static Lists

Profiles can be added to static lists either manually or using rule actions. Once a profile is added to a static list, you can only remove the profile by manually editing the list.

Scoring Plans

Scoring plans are a digital marketing tool that increment a score on a profile when certain conditions are met. You can also create advanced conditions to increment scores on profiles.

Custom plugins

Developers can implement custom plugins to provide new conditions or actions, and deploy predefined rules, property types, or any other functionality that may be implemented using OSGi bundles. jCustomer is also an OSGi application.

Technical architecture

jCustomer is a Apache Karaf (OSGi) application. jCustomer runs as a server-based Java service that is accessible through a REST API defined as part of the OASIS Context Server specification. As jCustomer uses an OSGi engine at its core, it is extensible and very flexible in terms of deployment scenarios. It is also designed to scale out since it uses cluster-tested technologies such as Elasticsearch, Apache Karaf Cellar (based on Hazelcast) and REST-API level-load distribution.

technical.png

The REST API is built using Apache CXF based on Java Beans that are automatically mapped as REST endpoints. Custom plugins may define new REST APIs to extend the built-in API functionality.

Items and scope

jCustomer structures the information it collects using the concept of Item which provides the base the context server needs to process and store the data. Items are persisted according to their type (structure) and identifier (identity). This base structure can be extended, if needed, using properties in the form of key-value pairs.

Additionally, tracked items are also gathered by scope which allows the context server to group together related items. Scopes usually pertain to a given site being analyzed, though they can span across sites depending on the desired analysis granularity. Scopes allow clients accessing the context server to filter data to only see relevant data.


{
    itemType: <type of the item>,
    scope: <scope>,
    itemId: <item identifier>,
    properties: <optional properties>
}

jCustomer defines a built-in scope (called systemscope) that clients can use to share data across scopes.

Events

Users' actions are conveyed from clients to the context server using events. Of course, the required information depends on what is collected and users' interactions with the observed systems but events minimally provide a type, a scope and source and target items. You can imagine an event as being a sentence, the event's type being the verb, the source the subject and the target the object:

{
    eventType: <type of the event>,
    scope: <scope of the event>,
    source: <Item>,
    target: <Item>,
    properties: <optional properties>
}

Profiles

By processing events, jCustomer progressively builds a picture of who the user is and how they behave. This knowledge is embedded in Profile objects. A profile is an Item with any number of properties and optional segments and scores. jCustomer provides default properties to cover common data (name, last name, age, email, etc.) as well as default segments to categorize users. jCustomer users are, however, free and even encouraged to create additional properties and segments to better suit their needs.

Items and types

Any information that is processed by and stored in jCustomer is structured as an Item. However, items only define a basic, generic structure. Types provide additional structure and semantics to generic items. By defining a new type, users specify which properties (including the type of value they accept) are available to items of that specific type.

Some types can be dynamically defined at runtime by calling the REST API while other extensions are done via jCustomer plugins. Part of extending jCustomer, therefore, is a matter of defining new types and specifying which kind of jCustomer entity (e.g. profiles) they can be affected to. For example, the following JSON document can be passed to jCustomer to declare a new property type identified (and named) tweetNb, tagged with the social tag, targeting profiles and using the integer value type.

{
    itemId: 'tweetNb', 
    itemType: 'propertyType',
    metadata: {
        id: 'tweetNb',
        name: 'tweetNb'
    },
    tags: ['social'],
    target: 'profiles',
    type: 'integer'
}

Learn more

The jCustomer data model, detailed in the Apache Unomi documentation is a great source of information to understand the relationship between various entities. You can also get a better understanding of Apache Unomi REST API in its dedicated documentation.