Added: incubator/unomi/website/manual/latest/extending-plugins.html URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/latest/extending-plugins.html?rev=1845794&view=auto ============================================================================== --- incubator/unomi/website/manual/latest/extending-plugins.html (added) +++ incubator/unomi/website/manual/latest/extending-plugins.html Mon Nov 5 14:08:37 2018 @@ -0,0 +1,206 @@ +<!DOCTYPE html> +<html lang="en"> +<head> +<meta charset="UTF-8"> +<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> +<meta name="generator" content="Asciidoctor 1.5.6.1"> +<title>Types vs. instances</title> +<link rel="stylesheet" href="./apache.css"> +</head> +<body class="article"> +<div id="header"> +<div id="toc" class="toc"> +<div id="toctitle">Table of Contents</div> +<ul class="sectlevel2"> +<li><a href="#_types_vs_instances">Types vs. instances</a></li> +<li><a href="#_plugin_structure">Plugin structure</a></li> +<li><a href="#_extension_points">Extension points</a></li> +<li><a href="#_other_unomi_entities">Other Unomi entities</a></li> +</ul> +</div> +</div> +<div id="content"> +<div class="paragraph"> +<p>Unomi is architected so that users can provided extensions in the form of plugins.</p> +</div> +<div class="sect2"> +<h3 id="_types_vs_instances">Types vs. instances</h3> +<div class="paragraph"> +<p>Several extension points in Unomi rely on the concept of type: the extension defines a prototype for what the actual items will be once parameterized with values known only at runtime. This is similar to the concept of classes in object-oriented programming: types define classes, providing the expected structure and which fields are expected to be provided at runtime, that are then instantiated when needed with actual values.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_plugin_structure">Plugin structure</h3> +<div class="paragraph"> +<p>Being built on top of Apache Karaf, Unomi leverages OSGi to support plugins. A Unomi plugin is, thus, an OSGi bundle specifying some specific metadata to tell Unomi the kind of entities it provides. A plugin can provide the following entities to extend Unomi, each with its associated definition (as a JSON file), located in a specific spot within the <code>META-INF/cxs/</code> directory of the bundle JAR file:</p> +</div> +<table class="tableblock frame-all grid-all spread"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<thead> +<tr> +<th class="tableblock halign-left valign-top">Entity</th> +<th class="tableblock halign-left valign-top">Location in <code>cxs</code> directory</th> +</tr> +</thead> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">ActionType</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">actions</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">ConditionType</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">conditions</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">Persona</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">personas</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">PropertyMergeStrategyType</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">mergers</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">PropertyType</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">properties then profiles or sessions subdirectory then <code><category name></code> directory</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">Rule</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">rules</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">Scoring</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">scorings</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">Segment</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">segments</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">ValueType</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">values</p></td> +</tr> +</tbody> +</table> +<div class="paragraph"> +<p><a href="http://aries.apache.org/modules/blueprint.html";>Blueprint</a> is used to declare what the plugin provides and inject any required dependency. The Blueprint file is located, as usual, at <code>OSGI-INF/blueprint/blueprint.xml</code> in the bundle JAR file.</p> +</div> +<div class="paragraph"> +<p>The plugin otherwise follows a regular maven project layout and should depend on the Unomi API maven artifact:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlight"><code class="language-xml" data-lang="xml"><dependency> + <groupId>org.apache.unomi</groupId> + <artifactId>unomi-api</artifactId> + <version>...</version> +</dependency></code></pre> +</div> +</div> +<div class="paragraph"> +<p>Some plugins consists only of JSON definitions that are used to instantiate the appropriate structures at runtime while some more involved plugins provide code that extends Unomi in deeper ways.</p> +</div> +<div class="paragraph"> +<p>In both cases, plugins can provide more that one type of extension. For example, a plugin could provide both `ActionType`s and `ConditionType`s.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_extension_points">Extension points</h3> +<div class="sect3"> +<h4 id="_actiontype">ActionType</h4> +<div class="paragraph"> +<p><code>ActionType`s define new actions that can be used as consequences of Rules being triggered. When a rule triggers, it creates new actions based on the event data and the rule internal processes, providing values for parameters defined in the associated `ActionType</code>. Example actions include: âSet user property x to value yâ or âSend a message to service xâ.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_conditiontype">ConditionType</h4> +<div class="paragraph"> +<p>`ConditionType`s define new conditions that can be applied to items (for example to decide whether a rule needs to be triggered or if a profile is considered as taking part in a campaign) or to perform queries against the stored Unomi data. They may be implemented in Java when attempting to define a particularly complex test or one that can better be optimized by coding it. They may also be defined as combination of other conditions. A simple condition could be: âUser is maleâ, while a more generic condition with parameters may test whether a given property has a specific value: âUser property x has value yâ.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_persona">Persona</h4> +<div class="paragraph"> +<p>A persona is a "virtual" profile used to represent categories of profiles, and may also be used to test how a personalized experience would look like using this virtual profile. A persona can define predefined properties and sessions. Persona definition make it possible to âemulateâ a certain type of profile, e.g : US visitor, non-US visitor, etc.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_propertymergestrategytype">PropertyMergeStrategyType</h4> +<div class="paragraph"> +<p>A strategy to resolve how to merge properties when merging profile together.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_propertytype">PropertyType</h4> +<div class="paragraph"> +<p>Definition for a profile or session property, specifying how possible values are constrained, if the value is multi-valued (a vector of values as opposed to a scalar value). `PropertyType`s can also be categorized using systemTags or file system structure, using sub-directories to organize definition files.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_rule">Rule</h4> +<div class="paragraph"> +<p>`Rule`s are conditional sets of actions to be executed in response to incoming events. Triggering of rules is guarded by a condition: the rule is only triggered if the associated condition is satisfied. That condition can test the event itself, but also the profile or the session. Once a rule triggers, a list of actions can be performed as consequences. Also, when rules trigger, a specific event is raised so that other parts of Unomi can react accordingly.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_scoring">Scoring</h4> +<div class="paragraph"> +<p>`Scoring`s are set of conditions associated with a value to assign to profiles when matching so that the associated users can be scored along that dimension. Each scoring element is evaluated and matching profiles' scores are incremented with the associated value.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_segments">Segments</h4> +<div class="paragraph"> +<p>`Segment`s represent dynamically evaluated groups of similar profiles in order to categorize the associated users. To be considered part of a given segment, users must satisfies the segmentâs condition. If they match, users are automatically added to the segment. Similarly, if at any given point during, they cease to satisfy the segmentâs condition, they are automatically removed from it.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_tag">Tag</h4> +<div class="paragraph"> +<p>`Tag`s are simple labels that are used to classify all other objects inside Unomi.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_valuetype">ValueType</h4> +<div class="paragraph"> +<p>Definition for values that can be assigned to properties ("primitive" types).</p> +</div> +</div> +</div> +<div class="sect2"> +<h3 id="_other_unomi_entities">Other Unomi entities</h3> +<div class="sect3"> +<h4 id="_userlist">UserList</h4> +<div class="paragraph"> +<p>User list are simple static lists of users. The associated profile stores the lists it belongs to in a specific property.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_goal">Goal</h4> +<div class="paragraph"> +<p>Goals represent tracked activities / actions that can be accomplished by site (or more precisely scope) visitors. These are tracked in general because they relate to specific business objectives or are relevant to measure site/scope performance.</p> +</div> +<div class="paragraph"> +<p>Goals can be defined at the scope level or in the context of a particular <code>Campaign</code>. Either types of goals behave exactly the same way with the exception of two notable differences: + - duration: scope-level goals are considered until removed while campaign-level goals are only considered for the campaign duration + - audience filtering: any visitor is considered for scope-level goals while campaign-level goals only consider visitors who match the campaign’s conditions</p> +</div> +</div> +<div class="sect3"> +<h4 id="_campaign">Campaign</h4> +<div class="paragraph"> +<p>A goal-oriented, time-limited marketing operation that needs to be evaluated for return on investment performance by tracking the ratio of visits to conversions.</p> +</div> +</div> +</div> +</div> +<div id="footer"> +<div id="footer-text"> +Last updated 2018-09-10 11:30:03 CEST +</div> +</div> +</body> +</html> \ No newline at end of file
Added: incubator/unomi/website/manual/latest/getting-started.html URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/latest/getting-started.html?rev=1845794&view=auto ============================================================================== --- incubator/unomi/website/manual/latest/getting-started.html (added) +++ incubator/unomi/website/manual/latest/getting-started.html Mon Nov 5 14:08:37 2018 @@ -0,0 +1,162 @@ +<!DOCTYPE html> +<html lang="en"> +<head> +<meta charset="UTF-8"> +<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> +<meta name="generator" content="Asciidoctor 1.5.6.1"> +<title>Getting started with Unomi</title> +<link rel="stylesheet" href="./apache.css"> +</head> +<body class="article"> +<div id="header"> +<div id="toc" class="toc"> +<div id="toctitle">Table of Contents</div> +<ul class="sectlevel2"> +<li><a href="#_getting_started_with_unomi">Getting started with Unomi</a></li> +</ul> +</div> +</div> +<div id="content"> +<div class="sect2"> +<h3 id="_getting_started_with_unomi">Getting started with Unomi</h3> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="sect3"> +<h4 id="_prerequisites">Prerequisites</h4> +<div class="paragraph"> +<p>This document assumes that you are already familiar with Unomi’s <a href="concepts.html">concepts</a>. On the technical side, we also assume working knowledge of <a href="https://git-scm.com/";>git</a> 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 <a href="http://www.oracle.com/technetwork/java/javase/";>http://www.oracle.com/technetwork/java/javase/</a> for details on how to download and install Java SE 7 or greater.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_running_unomi">Running Unomi</h4> +<div class="sect4"> +<h5 id="_start_unomi">Start Unomi</h5> +<div class="paragraph"> +<p>Start Unomi according to the <a href="5-min-quickstart.html">5 minute quick start</a> or by compiling using the building <a href="building-and-deploying.html#Deploying_the_generated_package">instructions</a>. Once you have Karaf running, + you should wait until you see the following messages on the Karaf console:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlight"><code>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...</code></pre> +</div> +</div> +<div class="paragraph"> +<p>This indicates that all the Unomi services are started and ready to react to requests. You can then open a browser and go to <code><a href="http://localhost:8181/cxs"; class="bare">http://localhost:8181/cxs</a></code> to see the list of +available RESTful services or retrieve an initial context at <code><a href="http://localhost:8181/context.json"; class="bare">http://localhost:8181/context.json</a></code> (which isn’t very useful at this point).</p> +</div> +</div> +<div class="sect4"> +<h5 id="_request_examples">Request examples</h5> +<div class="sect5"> +<h6 id="_retrieving_your_first_context">Retrieving your first context</h6> +<div class="paragraph"> +<p>You can retrieve a context using curl like this :</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlight"><code>curl http://localhost:8181/context.js?sessionId=1234</code></pre> +</div> +</div> +<div class="paragraph"> +<p>This will retrieve a JavaScript script that contains a <code>cxs</code> 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).</p> +</div> +</div> +<div class="sect5"> +<h6 id="_retrieving_a_context_as_a_json_object">Retrieving a context as a JSON object.</h6> +<div class="paragraph"> +<p>If you prefer to retrieve a pure JSON object, you can simply use a request formed like this:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlight"><code>curl http://localhost:8181/context.json?sessionId=1234</code></pre> +</div> +</div> +</div> +<div class="sect5"> +<h6 id="_accessing_profile_properties_in_a_context">Accessing profile properties in a context</h6> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>Here is an example that will retrieve all the session and profile properties.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlight"><code>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</code></pre> +</div> +</div> +<div class="paragraph"> +<p>The <code>requiredProfileProperties</code> and <code>requiredSessionProperties</code> 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 <a href="http://unomi.incubator.apache.org/unomi-api/apidocs/org/apache/unomi/api/ContextRequest.html";>ContextRequest</a> +Java class.</p> +</div> +</div> +<div class="sect5"> +<h6 id="_sending_events_using_the_context_servlet">Sending events using the context servlet</h6> +<div class="paragraph"> +<p>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:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlight"><code>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</code></pre> +</div> +</div> +<div class="paragraph"> +<p>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).</p> +</div> +</div> +<div class="sect5"> +<h6 id="_sending_events_using_the_eventcollector_servlet">Sending events using the eventcollector servlet</h6> +<div class="paragraph"> +<p>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:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="highlight"><code>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</code></pre> +</div> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +</div> +</div> +<div class="sect4"> +<h5 id="_where_to_go_from_here">Where to go from here</h5> +<div class="ulist"> +<ul> +<li> +<p>Read the <a href="twitter-samples.html">Twitter samples</a> documentation that contains a detailed example of how to integrate with Apache Unomi.</p> +</li> +</ul> +</div> +</div> +</div> +</div> +</div> +<div id="footer"> +<div id="footer-text"> +Last updated 2018-11-02 16:02:51 CET +</div> +</div> +</body> +</html> \ No newline at end of file Added: incubator/unomi/website/manual/latest/images/asf_logo_url.png URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/latest/images/asf_logo_url.png?rev=1845794&view=auto ============================================================================== Binary file - no diff available. Propchange: incubator/unomi/website/manual/latest/images/asf_logo_url.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: incubator/unomi/website/manual/latest/images/incubator-logo.png URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/latest/images/incubator-logo.png?rev=1845794&view=auto ============================================================================== Binary file - no diff available. Propchange: incubator/unomi/website/manual/latest/images/incubator-logo.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: incubator/unomi/website/manual/latest/images/unomi-request.png URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/latest/images/unomi-request.png?rev=1845794&view=auto ============================================================================== Binary file - no diff available. Propchange: incubator/unomi/website/manual/latest/images/unomi-request.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream
