3.1. Getting started with Unomi

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.

3.1.1. Prerequisites

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.

3.1.2. Running Unomi

Start Unomi

Start Unomi according to the 5 minute quick start or by compiling using the building 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 ofavailable 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 userprofile, segments, scores as well as functions that makes it easier to perform further requests (such as collectingevents 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 ofthe profile or session properties. If you need this data, you must send a JSON object to configure the resulting outputof 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 namesthat should be retrieved. In this case we use the wildcard character '*' to say we want to retrieve all the availableproperties. The structure of the JSON object that you should send is a JSON-serialized version of the ContextRequestJava 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 asillustrated 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 hasfinished loading you could either do a second call and get an updating context, or if you don’t need the context and wantto 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 optimizedrespond 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 loadedto 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.