Integrating with jExperience

November 14, 2023

If you are not familiar with jExperience, you can visit jExperience's Academy page for further technical information. There are two main modules responsible for integration with jExperience:

  • commerce-io-front-end
    This module registers conditions by extending jExperience
  • commerce-io-mf-bridge
    This module sends events to jExperience

Event types

Commerce IO sends several events to jExperience to store information about important user activities. The:

  • CommerceIOViewEvent event applies to page and product views. Depending on context, the event will either contain information on the product or the context, such as brand or category.
  • CommerceIOAddToCart event sends information about a product added to cart.
  • CommerceIOProductsPurchased event sends information about checkout along with a list of SKUs in the cart and relevant product data.

Sending events

To send events to MF, Commerce IO relies on a jExperience API accessible from a WEM object, which jExperience injects on the window. Commerce IO ensures that an event can be sent before sending it. There is also a time out of 500ms to prevent long waits. You can find more details in the sample event model included at the top of the /src/main/javascript/mf/mfintegration.js file. The processEvent() function is triggered from React components but some events are sent using a different mechanism.

On the product page, the SEO filter injects a script that includes an event listener for the checkout button. You can look at SEO filter for more details. To be able to attach an event to the button which comes from a SAP Hybris fragment, Commerce IO marks it with the “js-add-to-cart” class. When the button is clicked, a function similar to processEvent() is executed. An almost identical mechanism is used for checkout when a user is redirected to the “order” page.

Conditions building

Building conditions is simple and in most cases involves copying, renaming and adapting existing conditions. Note that conditions follow a very strict naming policy and you should keep your condition consistent with what was created in the commerce-io-mf-bridge module.

There are three main ingredients for conditions: angular controller, condition JSON file and resource bundle.

Angular controllers are placed inside the /src/main/javascript/marketing-factory/common/angular/conditions folder.

Remember to follow naming exactly as shown in examples.

For an example of single value condition, see the  condition-productViewEventCondition.controller.js file. For an example of a multi value condition, see the  condition-categoryViewEventCondition.controller.js file. These two conditions should provide you with a model for creating conditions, depending on what type of condition you require.

Condition JSON files are placed inside the /src/main/resources/META-INF/marketing-factory/conditions folder and provide the rules that will be used by UNOMI to evaluate these conditions. Once again strict naming rules apply. Note that propertyName points at the value in your event object and propertyValue points at the parameter that you specify in your controller.

To see your condition in Edit mode, you must name it, which you can do by providing an appropriate resource key in /src/main/resources/resources.

Strict naming convention apply to the name. Ensure that you provide a name that is similar in syntax to other names in the file.

Once you create your condition, redeploy your module and your condition should be visible.