We will first get you up and running with an example. We will then lift the corner of the cover somewhat and explain in greater details what just happened.


This document assumes that you are already familiar with Unomi’s concepts. On the technical side, we also assume working knowledge of git to be able to retrieve the code for Unomi and the example. Additionnally, you will require a working Java 7 or above install. Refer to http://www.oracle.com/technetwork/java/javase/ for details on how to download and install Java SE 7 or greater.

Running Unomi

Building Unomi

  1. Get the code: git clone https://git-wip-us.apache.org/repos/asf/incubator-unomi.git
  2. Build and install according to the instructions and install Unomi.

Start Unomi

Start Unomi according to the instructions. Once you have Karaf running, you should wait until you see the following messages on the Karaf console:

Initializing user list service endpoint...
Initializing geonames service endpoint...
Initializing segment service endpoint...
Initializing scoring service endpoint...
Initializing campaigns service endpoint...
Initializing rule service endpoint...
Initializing profile service endpoint...
Initializing cluster service endpoint...

This indicates that all the Unomi services are started and ready to react to requests. You can then open a browser and go to http://localhost:8181/cxs to see the list of available RESTful services or retrieve an initial context at http://localhost:8181/context.json (which isn’t very useful at this point).

Request examples

Retrieving your first context

You can retrieve a context using curl like this :

curl http://localhost:8181/context.js?sessionId=1234

This will retrieve a JavaScript script that contains a cxs object that contains the context with the current user profile, segments, scores as well as functions that makes it easier to perform further requests (such as collecting events using the cxs.collectEvents() function).

Retrieving a context as a JSON object.

If you prefer to retrieve a pure JSON object, you can simply use a request formed like this:

curl http://localhost:8181/context.json?sessionId=1234

Accessing profile properties in a context

By default, in order to optimize the amount of data sent over the network, Apache Unomi will not send the content of the profile or session properties. If you need this data, you must send a JSON object to configure the resulting output of the context.js(on) servlet.

Here is an example that will retrieve all the session and profile properties.

curl -H "Content-Type: application/json" -X POST -d '{"source":{"itemId":"homepage","itemType":"page","scope":"example"},"requiredProfileProperties":["*"],"requiredSessionProperties":["*"],"requireSegments":true}' http://localhost:8181/context.json?sessionId=1234

The requiredProfileProperties and requiredSessionProperties are properties that take an array of property names that should be retrieved. In this case we use the wildcard character ‘*’ to say we want to retrieve all the available properties. The structure of the JSON object that you should send is a JSON-serialized version of the ContextRequest Java class.

Sending events using the context servlet

At the same time as you are retrieving the context, you can also directly send events in the ContextRequest object as illustrated in the following example:

curl -H "Content-Type: application/json" -X POST -d '{"source":{"itemId":"homepage","itemType":"page","scope":"example"},"events":[{"eventType":"view","scope": "example","source":{"itemType": "site","scope":"example","itemId": "mysite"},"target":{"itemType":"page","scope":"example","itemId":"homepage","properties":{"pageInfo":{"referringURL":""}}}}]}' http://localhost:8181/context.json?sessionId=1234

Upon received events, Apache Unomi will execute all the rules that match the current context, and return an updated context. This way of sending events is usually used upon first loading of a page. If you want to send events after the page has finished loading you could either do a second call and get an updating context, or if you don’t need the context and want to send events in a network optimal way you can use the eventcollector servlet (see below).

Sending events using the eventcollector servlet

If you only need to send events without retrieving a context, you should use the eventcollector servlet that is optimized respond quickly and minimize network traffic. Here is an example of using this servlet:

curl -H "Content-Type: application/json" -X POST -d '{"events":[{"eventType":"view","scope": "example","source":{"itemType": "site","scope":"example","itemId": "mysite"},"target":{"itemType":"page","scope":"example","itemId":"homepage","properties":{"pageInfo":{"referringURL":""}}}}]}' http://localhost:8181/eventcollector?sessionId=1234

Note that the eventcollector executes the rules but does not return a context. If is generally used after a page is loaded to send additional events.

Where to go from here

  • Read the Twitter sample documentation that contains a detailed example of how to integrate with Apache Unomi.

Back to top

Reflow Maven skin by Andrius Velykis.