Talking to the Unomi events API

(I am assuming you already have Unomi up and running in your machine. If you don't, please check Unomi out of the box)

There is a small module inside Unomi called WAB that implements the basic User Events endpoints, defined following the Apache Blueprint format, in resources/OSGI-INF.blueprint. They are:

/context.js, /context.json

Its logic is defined in the ContextServlet.java file. This endpoint is meant to do the communication for both the webpage and Unomi. In other words, it lets you update user’s information sending user events and receive user information using its session id.

The following is an example of request that can be sent to the context endpoint.

curl -X POST \
  'http://localhost:8181/context.js?sessionId=321839218' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: de6d8d95-fe69-438f-865a-214843956db6' \
  -d '{
   "source":{
       "itemType":"pageView",
       "scope":"the-coolest-website",
       "itemId":"pageView",
   },
   "events":[
      {
         "eventType":"myAwesomeUserEvent",
         "scope":"the-coolest-website",
         "source":{
            "itemType":"pageView",
            "scope":"the-coolest-website",
            "itemId":"pageView",
            "properties":{
               "myProperty":"myValue"
            }
         }
      }
   ],
   "requiredProfileProperties":[
      "myProperty"
   ],
   "requireSegments": true
}'

There are some important elements of this request that we need to understand, so we will talk a bit about them before going any further.

events is an array of user events that a product can send to Unomi. They have eventType, scope and source. This is usually the start of the flow for Unomi, and it already has an implemented condition called eventTypeCondition that deals with Events evaluating its eventType. Scope is not used by default, but it is used to differentiate events from different sources, if you have multiple products using Unomi, for example. Source is, basically, the definition of where the data is coming from. When you want to send some data from a user event, you usually send them through source.properties.

requiredProfileProperties is an array with the profile properties that you want to receive back. By default, Unomi does not return anything, so it can run as fast as possible. So, if you need to know any information about the user interacting with your properties, you need to define them here.

requireSegments is a boolean that works as above. Unomi does not send the profile’s segments by default. If you need them, you need to ask them.

The responses for this request are shown below (for .json and .js, in that order):

{
    "profileId": "2efca8c0-2c73-4da1-88ae-0d4d13e8ec2d",
    "sessionId": "321839218",
    "profileProperties": {},
    "sessionProperties": null,
    "profileSegments": [
        "returningProductUser"
    ],
    "filteringResults": null,
    "personalizations": null,
    "trackedConditions": [],
    "anonymousBrowsing": false,
    "consents": {}
}

For the .js endpoint, this is what you get:

window.digitalData = window.digitalData || {};
var cxs = {"profileId":"2efca8c0-2c73-4da1-88ae-0d4d13e8ec2d","sessionId":"321839218","profileProperties":{},"sessionProperties":null,"profileSegments":["returningProductUser"],"filteringResults":null,"personalizations":null,"trackedConditions":[],"anonymousBrowsing":false,"consents":{}};

As you can see, it returns an empty object for profile properties. This happens because the profile does not have the property “myProperty” that we asked for.

/eventcollector

Its logic is defined in the EventsCollectorServlet.java file. It is meant to be and endpoint for just updating the system with user events, without getting the profile information in return. Its payload looks like the one below:

curl -X POST \
  http://localhost:8181/eventcollector \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
   "sessionId": "392183982139812",
   "events":[
      {
         "eventType":"myAwesomeUserEvent",
         "scope":"the-coolest-website",
         "source":{
            "itemType":"pageView",
            "scope":"the-coolest-website",
            "itemId":"pageView",
            "properties":{
               "myProperty":"myValue"
            }
         }
      }
   ] 
}

And it responds with a simple:

{
    "updated": 0
}

That’s pretty much it.

/client/myprofile (.json/.csv/.text/.yaml)

Its logic is defined in the ClientServlet.java file. It’s a GET endpoint that lets you see all properties your current profile holds. When performing a GET /client/myprofile.json, this is what I got:

{
    "nbOfVisits": 1,
    "productVisitedSite": [],
    "productVisitedSiteNb": 0,
    "lastVisit": "2018-11-09T12:46:55Z",
    "firstVisit": "2018-11-09T12:46:55Z"
}

All this was to give an Overview of what’s already implemented when you want to feed Apache Unomi with User Events. The way of feeding Unomi with Context data may vary.