This is an automated email from the ASF dual-hosted git repository.
shuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/unomi.git
The following commit(s) were added to refs/heads/master by this push:
new cdfbfb6 UNOMI-208 Improve documentation - Fixed flow by fixing
heading levels that were not correct - Moved the request examples to a separate
document to make them more visible - Moved the consent API higher up - Made all
curl examples that use POST bodies use multiline bodies to make them easier to
read - Made the web tracker also stand out some more
cdfbfb6 is described below
commit cdfbfb6b926fc4300ed56c1a02832141d0db4aec
Author: Serge Huber <shu...@apache.org>
AuthorDate: Sun May 12 10:12:36 2019 +0200
UNOMI-208 Improve documentation
- Fixed flow by fixing heading levels that were not correct
- Moved the request examples to a separate document to make them more
visible
- Moved the consent API higher up
- Made all curl examples that use POST bodies use multiline bodies to make
them easier to read
- Made the web tracker also stand out some more
Signed-off-by: Serge Huber <shu...@apache.org>
---
manual/src/main/asciidoc/5-min-quickstart.adoc | 2 +-
manual/src/main/asciidoc/consent-api.adoc | 73 +++++++++-
manual/src/main/asciidoc/getting-started.adoc | 75 +---------
manual/src/main/asciidoc/index.adoc | 22 +--
manual/src/main/asciidoc/patches.adoc | 2 +-
manual/src/main/asciidoc/request-examples.adoc | 158 +++++++++++++++++++++
manual/src/main/asciidoc/useful-unomi-urls.adoc | 2 +-
.../{installing-tracker.adoc => web-tracker.adoc} | 10 +-
8 files changed, 246 insertions(+), 98 deletions(-)
diff --git a/manual/src/main/asciidoc/5-min-quickstart.adoc
b/manual/src/main/asciidoc/5-min-quickstart.adoc
index 5bb2e20..9a8b7f9 100644
--- a/manual/src/main/asciidoc/5-min-quickstart.adoc
+++ b/manual/src/main/asciidoc/5-min-quickstart.adoc
@@ -11,7 +11,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//
-==== Five Minutes QuickStart
+=== Five Minutes QuickStart
1) Install JDK 8
(http://www.oracle.com/technetwork/java/javase/downloads/index.html) and make
sure you set the
JAVA_HOME variable
https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/
diff --git a/manual/src/main/asciidoc/consent-api.adoc
b/manual/src/main/asciidoc/consent-api.adoc
index fad664f..fef63ec 100644
--- a/manual/src/main/asciidoc/consent-api.adoc
+++ b/manual/src/main/asciidoc/consent-api.adoc
@@ -13,7 +13,7 @@
//
=== Consent API
-Starting with Apache Unomi 1.3 (still in development), a new API for consent
management is now available. This API
+Starting with Apache Unomi 1.3, a new API for consent management is now
available. This API
is designed to be able to store/retrieve/update visitor consents in order to
comply with new
privacy regulations such as the
https://en.wikipedia.org/wiki/General_Data_Protection_Regulation[GDPR].
@@ -28,20 +28,45 @@ definitions, it only stores/retrieves consents for each
profile based on this ty
* a status date (the date at which the status was updated)
* a revocation date, in order to comply with GDPR this is usually set at two
years
-Here is an example of a Profile with a consent attached to it:
+Consents are stored as a sub-structure inside a profile. To retrieve the
consents of a profile
+you can simply retrieve a profile with the following request:
[source]
----
+curl -X POST http://localhost:8181/context.json?sessionId=1234 \
+-H "Content-Type: application/json" \
+-d @- <<'EOF'
{
- "profileId": "8cbe380f-57bb-419d-97bf-24bf30178550",
- "sessionId": "0d755f4e-154a-45c8-9169-e852e1d706d9",
+ "source": {
+ "itemId":"homepage",
+ "itemType":"page",
+ "scope":"example"
+ }
+}
+EOF
+----
+
+Here is an example of a response with a Profile with a consent attached to it:
+
+[source]
+----
+{
+ "profileId": "18afb5e3-48cf-4f8b-96c4-854cfaadf889",
+ "sessionId": "1234",
+ "profileProperties": null,
+ "sessionProperties": null,
+ "profileSegments": null,
+ "filteringResults": null,
+ "personalizations": null,
+ "trackedConditions": [],
+ "anonymousBrowsing": false,
"consents": {
"example/newsletter": {
"scope": "example",
"typeIdentifier": "newsletter",
"status": "GRANTED",
- "statusDate": "2018-05-22T09:44:33Z",
- "revokeDate": "2020-05-21T09:44:33Z"
+ "statusDate": "2018-05-22T09:27:09Z",
+ "revokeDate": "2020-05-21T09:27:09Z"
}
}
}
@@ -99,7 +124,41 @@ You could send it using the following curl request:
[source]
----
-curl -H "Content-Type: application/json" -X POST -d
'{"source":{"itemId":"homepage","itemType":"page","scope":"example"},"events":[{"scope":"example","eventType":"modifyConsent","source":{"itemType":"page","scope":"example","itemId":"anItemId"},"target":{"itemType":"anyType","scope":"example","itemId":"anyItemId"},"properties":{"consent":{"typeIdentifier":"newsletter","scope":"example","status":"GRANTED","statusDate":"2018-05-22T09:27:09.473Z","revokeDate":"2020-05-21T09:27:09.473Z"}}}]}
[...]
+curl -X POST http://localhost:8181/context.json?sessionId=1234 \
+-H "Content-Type: application/json" \
+-d @- <<'EOF'
+{
+ "source":{
+ "itemId":"homepage",
+ "itemType":"page",
+ "scope":"example"
+ },
+ "events": [
+ {
+ "scope":"example",
+ "eventType":"modifyConsent",
+ "source":{
+ "itemType":"page",
+ "scope":"example",
+ "itemId":"anItemId"
+ },
+ "target":{
+ "itemType":"anyType",
+ "scope":"example",
+ "itemId":"anyItemId"},
+ "properties":{
+ "consent":{
+ "typeIdentifier":"newsletter",
+ "scope":"example",
+ "status":"GRANTED",
+ "statusDate":"2018-05-22T09:27:09.473Z",
+ "revokeDate":"2020-05-21T09:27:09.473Z"
+ }
+ }
+ }
+ ]
+}
+EOF
----
==== How it works (internally)
diff --git a/manual/src/main/asciidoc/getting-started.adoc
b/manual/src/main/asciidoc/getting-started.adoc
index 6fc3a30..e478de6 100644
--- a/manual/src/main/asciidoc/getting-started.adoc
+++ b/manual/src/main/asciidoc/getting-started.adoc
@@ -44,76 +44,5 @@ 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 :
-
-[source]
-----
-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:
-
-[source]
-----
-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.
-
-[source]
-----
-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
http://unomi.incubator.apache.org/unomi-api/apidocs/org/apache/unomi/api/ContextRequest.html[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:
-
-[source]
-----
-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:
-
-[source]
-----
-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,Twitter sample>> documentation that contains a
detailed example of how to integrate with Apache Unomi.
\ No newline at end of file
+Now that your service is up and running you can go look at the
<<_request-examples,request examples>> to learn basic
+requests you can do once your server is up and running.
\ No newline at end of file
diff --git a/manual/src/main/asciidoc/index.adoc
b/manual/src/main/asciidoc/index.adoc
index a8c746f..c3eb2ba 100644
--- a/manual/src/main/asciidoc/index.adoc
+++ b/manual/src/main/asciidoc/index.adoc
@@ -32,16 +32,26 @@ include::5-min-quickstart.adoc[]
include::concepts.adoc[]
-== Setup
+== First steps with Apache Unomi
include::getting-started.adoc[]
-include::installing-tracker.adoc[]
+include::request-examples.adoc[]
+
+include::web-tracker.adoc[]
include::configuration.adoc[]
include::useful-unomi-urls.adoc[]
+== Consent management
+
+include::consent-api.adoc[]
+
+== Cluster setup
+
+include::clustering.adoc[]
+
== Integration samples
include::samples/samples.adoc[]
@@ -60,14 +70,6 @@ include::connectors/salesforce-connector.adoc[]
include::connectors/mailchimp-connector.adoc[]
-== Cluster setup
-
-include::clustering.adoc[]
-
-== Consent API
-
-include::consent-api.adoc[]
-
== Developers
include::building-and-deploying.adoc[]
diff --git a/manual/src/main/asciidoc/patches.adoc
b/manual/src/main/asciidoc/patches.adoc
index 3baba57..6c9e85f 100644
--- a/manual/src/main/asciidoc/patches.adoc
+++ b/manual/src/main/asciidoc/patches.adoc
@@ -11,7 +11,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//
-==== Migration patches
+=== Migration patches
You may provide patches on any predefined items by simply adding a JSON file
in :
diff --git a/manual/src/main/asciidoc/request-examples.adoc
b/manual/src/main/asciidoc/request-examples.adoc
new file mode 100644
index 0000000..123ff02
--- /dev/null
+++ b/manual/src/main/asciidoc/request-examples.adoc
@@ -0,0 +1,158 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+=== Request examples
+
+==== Retrieving your first context
+
+You can retrieve a context using curl like this :
+
+[source]
+----
+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:
+
+[source]
+----
+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.
+
+[source]
+----
+curl -X POST http://localhost:8181/context.json?sessionId=1234 \
+-H "Content-Type: application/json" \
+-d @- <<'EOF'
+{
+ "source": {
+ "itemId":"homepage",
+ "itemType":"page",
+ "scope":"example"
+ },
+ "requiredProfileProperties":["*"],
+ "requiredSessionProperties":["*"],
+ "requireSegments":true
+}
+EOF
+----
+
+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
http://unomi.incubator.apache.org/unomi-api/apidocs/org/apache/unomi/api/ContextRequest.html[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:
+
+[source]
+----
+curl -X POST http://localhost:8181/context.json?sessionId=1234 \
+-H "Content-Type: application/json" \
+-d @- <<'EOF'
+{
+ "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":""
+ }
+ }
+ }
+ }
+ ]
+}
+EOF
+----
+
+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:
+
+[source]
+----
+curl -X POST http://localhost:8181/context.json?sessionId=1234 \
+-H "Content-Type: application/json" \
+-d @- <<'EOF'
+{
+ "events":[
+ {
+ "eventType":"view",
+ "scope": "example",
+ "source":{
+ "itemType": "site",
+ "scope":"example",
+ "itemId": "mysite"
+ },
+ "target":{
+ "itemType":"page",
+ "scope":"example",
+ "itemId":"homepage",
+ "properties":{
+ "pageInfo":{
+ "referringURL":""
+ }
+ }
+ }
+ }
+ ]
+}
+EOF
+----
+
+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
+
+* You can find more <<_useful_apache_unomi_urls,useful Apache Unomi URLs>>
that can be used in the same way as the above examples.
+* You may want to know integrate the provided <<_web_tracker,web tracker>>
into your web site.
+* Read the <<_twitter_sample,Twitter sample>> documentation that contains a
detailed example of how to integrate with Apache Unomi.
\ No newline at end of file
diff --git a/manual/src/main/asciidoc/useful-unomi-urls.adoc
b/manual/src/main/asciidoc/useful-unomi-urls.adoc
index 2fe2e17..a091576 100644
--- a/manual/src/main/asciidoc/useful-unomi-urls.adoc
+++ b/manual/src/main/asciidoc/useful-unomi-urls.adoc
@@ -11,7 +11,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//
-==== Useful Apache Unomi URLs
+=== Useful Apache Unomi URLs
In this section we will list some useful URLs that can be used to quickly
access parts of Apache Unomi that can help
you understand or diagnose what is going on in the system.
diff --git a/manual/src/main/asciidoc/installing-tracker.adoc
b/manual/src/main/asciidoc/web-tracker.adoc
similarity index 98%
rename from manual/src/main/asciidoc/installing-tracker.adoc
rename to manual/src/main/asciidoc/web-tracker.adoc
index 186774d..349193b 100644
--- a/manual/src/main/asciidoc/installing-tracker.adoc
+++ b/manual/src/main/asciidoc/web-tracker.adoc
@@ -11,12 +11,12 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//
-==== Web Tracker
+=== Web Tracker
This extension is providing the web tracker to start collecting visitors data
on your website.
The tracker is implemented as an integration of
https://github.com/segmentio/analytics.js[analytics.js] for Unomi.
-===== Getting started
+==== Getting started
Extension can be tested at : `http://localhost:8181/tracker/index.html`
@@ -38,12 +38,12 @@ In your page include unomiOptions and include code snippet
from `snippet.min.js`
Check analytics.js API
https://segment.com/docs/sources/website/analytics.js/[here].
All methods can be used on `unomiTracker` object, although not all event types
are supported by Unomi intergation.
-===== How to contribute
+==== How to contribute
The source code is in the folder javascript with a package.json, the file to
update is `analytics.js-integration-apache-unomi.js` apply your modification in
this file then use the command `yarn build` to compile a new JS file.
Then you can use the test page to try your changes
`http://localhost:8181/tracker/index.html`.
-===== Tracking page views
+==== Tracking page views
By default the script will track page views, but maybe you want to take
control over this mechanism of add page views
to a single page application. In order to generate a page view
programmatically from Javascript you can use code similar
@@ -110,7 +110,7 @@ in Apache Unomi on profiles to indicate growing interest
over time for specific
will be accepted by Apache Unomi without needing to declare them previously
anywhere (the same is true for tags and
categories).
-===== Tracking form submissions
+==== Tracking form submissions
Using the web tracker you can also track form submissions. In order to do this
a few steps are required to get a form's
submission to be tracked and then its form values to be sent as events to
Apache Unomi. Finally setting up a rule to
