You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@unomi.apache.org by sh...@apache.org on 2018/11/23 17:07:55 UTC
svn commit: r1847294 - /incubator/unomi/website/manual/latest/index.html
Author: shuber
Date: Fri Nov 23 17:07:55 2018
New Revision: 1847294
URL: http://svn.apache.org/viewvc?rev=1847294&view=rev
Log:
Site checkin for project Apache Unomi :: Root Project
Modified:
incubator/unomi/website/manual/latest/index.html
Modified: incubator/unomi/website/manual/latest/index.html
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/latest/index.html?rev=1847294&r1=1847293&r2=1847294&view=diff
==============================================================================
--- incubator/unomi/website/manual/latest/index.html (original)
+++ incubator/unomi/website/manual/latest/index.html Fri Nov 23 17:07:55 2018
@@ -658,6 +658,277 @@ will be accepted by Apache Unomi without
categories).</p>
</div>
</div>
+<div class="sect4">
+<h5 id="_tracking_form_submissions">Tracking form submissions</h5>
+<div class="paragraph">
+<p>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
+react to the incoming event will help use the form values to perform any action that is desired.</p>
+</div>
+<div class="paragraph">
+<p>Let’s look at a concrete example. Before we get started you should know that this example is already available to
+directly test in Apache Unomi at the following URL :</p>
+</div>
+<div class="literalblock">
+<div class="content">
+<pre>http://localhost:8181/tracker</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Simply modify the form values and click submit and it will perform all the steps we are describing below.</p>
+</div>
+<div class="paragraph">
+<p>So here is the form we want to track :</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code><form id="testFormTracking" action="#" name="testFormTracking">
+ <label for="firstName">First name</label>
+ <input type="text" id="firstName" name="firstName" value="John"/>
+
+ <label for="lastName">Last name</label>
+ <input type="text" id="lastName" name="lastName" value="Doe"/>
+
+ <label for="email">Email</label>
+ <input type="email" id="email" name="email" value="johndoe@acme.com"/>
+
+ <input type="submit" name="submitButton" value="Submit"/>
+</form></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As you can see it’s composed of three fields - firstName, lastName and email - as well as a submit button. In order to
+track it we can add directly under the following snippet :</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code><script type="text/javascript">
+ window.addEventListener("load", function () {
+ var form = document.getElementById('testFormTracking');
+ unomiTracker.trackForm(form, 'formSubmitted', {formName: form.name});
+ });
+</script></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>What this snippet does is retrieve the form using its element ID and then uses the unomiTracker to track form submissions.
+Be careful to always use in the form event name a string that starts with <code>form</code> in order for the event to be sent back
+to Unomi. Also the form name is also a mandatory parameter that will be passed to Unomi inside a event of type <code>form</code> under
+the <code>target.itemId</code> property name.</p>
+</div>
+<div class="paragraph">
+<p>Here is an example of the event that gets sent back to Apache Unomi:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>{
+ "itemId" : "cd627012-963e-4bb5-97f0-480990b41254",
+ "itemType" : "event",
+ "scope" : "realEstateManager",
+ "version" : 1,
+ "eventType" : "form",
+ "sessionId" : "aaad09aa-88c2-67bd-b106-5a47ded43ead",
+ "profileId" : "48563fd0-6319-4260-8dba-ae421beba26f",
+ "timeStamp" : "2018-11-23T16:32:26Z",
+ "properties" : {
+ "firstName" : "John",
+ "lastName" : "Doe",
+ "email" : "johndoe@acme.com",
+ "submitButton" : "Submit"
+ },
+ "source" : {
+ "itemId" : "/tracker/",
+ "itemType" : "page",
+ "scope" : "realEstateManager",
+ "version" : null,
+ "properties" : {
+ "pageInfo" : {
+ "destinationURL" : "http://localhost:8181/tracker/?firstName=Bill&lastName=Gates&email=bgates%40microsoft.com",
+ "pageID" : "/tracker/",
+ "pagePath" : "/tracker/",
+ "pageName" : "Apache Unomi Web Tracker Test Page",
+ "referringURL" : "http://localhost:8181/tracker/?firstName=John&lastName=Doe&email=johndoe%40acme.com"
+ },
+ "attributes" : [ ],
+ "consentTypes" : [ ],
+ "interests" : { }
+ }
+ },
+ "target" : {
+ "itemId" : "testFormTracking",
+ "itemType" : "form",
+ "scope" : "realEstateManager",
+ "version" : null,
+ "properties" : { }
+ },
+ "persistent" : true
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>You can see in this event that the form values are sent as properties of the event itself, while the form name is sent
+as the <code>target.itemId</code></p>
+</div>
+<div class="paragraph">
+<p>While setting up form tracking, it can be very useful to use the Apache Unomi Karaf SSH shell commands : <code>event-tail</code>
+and <code>event-view</code> to check if you are properly receiving the form submission events and that they contain the expected
+data. If not, check your tracking code for any errors.</p>
+</div>
+<div class="paragraph">
+<p>Now that the data is properly sent using an event to Apache Unomi, we must still use it to perform some kind of actions.
+Using rules, we could do anything from updating the profile to sending the data to a third-party server (using a custom-
+developped action of course). In this example we will illustrate how to update the profile.</p>
+</div>
+<div class="paragraph">
+<p>In order to do so we will deploy a rule that will copy data coming from the event into a profile. But we will need to
+map the form field names to profile names, and this can be done using the <code>setPropertyAction</code> that’s available out of the
+box in the Apache Unomi server.</p>
+</div>
+<div class="paragraph">
+<p>There are two ways to register rules : either by building a custom OSGi bundle plugin or using the REST API to directly
+send a JSON representation of the rule to be saved. We will in this example use the CURL shell command to make a call to
+the REST API.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>curl -X POST -k -u karaf:karaf https://localhost:9443/cxs/rules \
+ --header "Content-Type: application/json" \
+-d @- << EOF
+{
+ "itemId": "form-mapping-example",
+ "itemType": "rule",
+ "linkedItems": null,
+ "raiseEventOnlyOnceForProfile": false,
+ "raiseEventOnlyOnceForSession": false,
+ "priority": -1,
+ "metadata": {
+ "id": "form-mapping-example",
+ "name": "Example Form Mapping",
+ "description": "An example of how to map event properties to profile properties",
+ "scope": "realEstateManager",
+ "tags": [],
+ "enabled": true,
+ "missingPlugins": false,
+ "hidden": false,
+ "readOnly": false
+ },
+ "condition": {
+ "type": "formEventCondition",
+ "parameterValues": {
+ "formId": "testFormTracking",
+ "pagePath" : "/tracker/"
+ }
+ },
+ "actions": [
+ {
+ "type": "setPropertyAction",
+ "parameterValues": {
+ "setPropertyName": "properties(firstName)",
+ "setPropertyValue": "eventProperty::properties(firstName)",
+ "setPropertyStrategy": "alwaysSet"
+ }
+ },
+ {
+ "type": "setPropertyAction",
+ "parameterValues": {
+ "setPropertyName": "properties(lastName)",
+ "setPropertyValue": "eventProperty::properties(lastName)",
+ "setPropertyStrategy": "alwaysSet"
+ }
+ },
+ {
+ "type": "setPropertyAction",
+ "parameterValues": {
+ "setPropertyName": "properties(email)",
+ "setPropertyValue": "eventProperty::properties(email)",
+ "setPropertyStrategy": "alwaysSet"
+ }
+ }
+ ]
+}
+EOF</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As you can see in this request, we have a few parameters that need explaining:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>-k</code> is used to accept any certificate as we are in this example using a default Apache Unomi server configuration that
+comes with its predefined HTTPS certificates</p>
+</li>
+<li>
+<p><code>-u karaf:karaf</code> is the default username/password for authenticating to the REST API. To change this value you should
+edit the `etc/users.properties`file and it is required to modify this login before going to production.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Finally the rule itself should be pretty self-explanatory but there are a few important things to note :</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>the <code>itemId</code> and <code>metadata.id</code> values should be the same</p>
+</li>
+<li>
+<p>the <code>scope</code> should be the same as the scope that was setup in the tracker initialization</p>
+</li>
+<li>
+<p>the <code>formId</code> parameter must have the form name value</p>
+</li>
+<li>
+<p>the <code>pagePath</code> should be the pagePath passed through the event (if you’re not sure of its value, you could either using
+network debugging in the browser or use the <code>event-tail</code> and <code>event-view</code> commands in the Apache Unomi Karaf SSH shell).</p>
+</li>
+<li>
+<p>the setPropertyAction may be repeated as many times as desired to copy the values from the event to the profile. Note that
+the <code>setPropertyName</code> will define the property to set on the profile and the <code>setPropertyValue</code> will define where the
+value is coming from. In this example the name and the value are the same but that is no way a requirement. It could
+even be possible to using multiple <code>setPropertyAction</code> instances to copy the same event property into different profile
+properties.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>To check if your rule is properly deployed you can use the following SSH shell command :</p>
+</div>
+<div class="paragraph">
+<p><code>unomi:rule-view form-mapping-example</code></p>
+</div>
+<div class="paragraph">
+<p>The parameter is the <code>itemId</code> of the rule. If you want to see all the rules deployed in the system you can use the
+command :</p>
+</div>
+<div class="paragraph">
+<p><code>unomi:rule-list 1000</code></p>
+</div>
+<div class="paragraph">
+<p>The <code>1000</code> parameter is the limit of number of objects to retrieve. As the number of rules can grow quickly in an Apache
+Unomi instance, it is recommended to put this value a bit high to make sure you get the full list of rules.</p>
+</div>
+<div class="paragraph">
+<p>Once the rule is in place, try submitting the form with some values and check that the profile is properly updated. One
+recommend way of doing this is to use the <code>event-tail</code> command that will output something like this :</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>ID |Type |Session |Profile |Timestamp |Scope |Persi|
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+cef09b89-6b99-4e4f-a99c-a4159a66b42b|form |aaad09aa-88c2-67bd-b106-5a47ded43ead|48563fd0-6319-4260-8dba-ae421beba26f|Fri Nov 23 17:52:33 CET 2018 |realEstateManag|true |</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>You can directly see the profile that is being used, so you can then simply use the</p>
+</div>
+<div class="paragraph">
+<p><code>unomi:profile-view 48563fd0-6319-4260-8dba-ae421beba26f</code></p>
+</div>
+<div class="paragraph">
+<p>command to see a JSON dump of the profile and check that the form values have been properly positioned.</p>
+</div>
+</div>
</div>
</div>
<div class="sect2">