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 b8fee5f UNOMI-300 Fix npm dependencies for web tracker Add
documentation about implicit page views
b8fee5f is described below
commit b8fee5f55023b93c6422e6e1de1f20b383bf130e
Author: Serge Huber <[email protected]>
AuthorDate: Tue May 5 12:20:36 2020 +0200
UNOMI-300 Fix npm dependencies for web tracker
Add documentation about implicit page views
---
extensions/web-tracker/javascript/README.md | 59 ++++++++++++++++++++++++++---
manual/src/main/asciidoc/web-tracker.adoc | 51 +++++++++++++++++++++++--
2 files changed, 101 insertions(+), 9 deletions(-)
diff --git a/extensions/web-tracker/javascript/README.md
b/extensions/web-tracker/javascript/README.md
index 06b6ffe..2ab1d5a 100644
--- a/extensions/web-tracker/javascript/README.md
+++ b/extensions/web-tracker/javascript/README.md
@@ -16,14 +16,12 @@
-->
-Apache Unomi Web Tracker
-=================================
+Apache Unomi Web Tracker Javascript Library
+===========================================
This is the web tracker for apache-unomi ( http://unomi.apache.org/ )
-It's included in unomi server, and can be served directly by unomi :
https://github.com/apache/incubator-unomi/tree/master/extensions/web-tracker
-
-This package can be used in a JS app to interact with unomi.
+This package can be used in a Javascript application to interact with Apache
Unomi.
## Getting started
@@ -46,7 +44,53 @@ unomiTracker.ready(function() {
});
```
-Then send events :
+## Implicit page view event
+
+In the initialize call, the tracker will generate an implicit page view event,
which by default will be populated with
+the following information:
+
+```javascript
+ window.digitalData.page = window.digitalData.page || {
+ path: location.pathname + location.hash,
+ pageInfo: {
+ pageName: document.title,
+ pageID : location.pathname + location.hash,
+ pagePath : location.pathname + location.hash,
+ destinationURL: location.href
+ }
+ }
+```
+
+Now if you want to provide your own custom page information for the initial
page view, you can simply do it like this:
+
+````javascript
+ unomiTracker.initialize({
+ scope: 'myScope',
+ url: 'http://unomi:8181', // we use an empty URL to make it
relative to this page.
+ initialPageProperties: {
+ path: path,
+ pageInfo: {
+ destinationURL: location.href,
+ tags: ["tag1", "tag2", "tag3"],
+ categories: ["category1", "category2", "category3"]
+ },
+ interests: {
+ "interest1": 1,
+ "interest2": 2,
+ "interest3": 3
+ }
+ }
+ });
+````
+
+Also note that the FIRST call to unomiTracker.page() will be IGNORED because
of this initial page view. This is the
+way that the Analytics.js library handles it. So make sure you are aware of
this when calling it. This is to avoid having
+two page views on a single call and to be compatible with old versions that
did use the explicit call.
+
+## Sending events
+
+Here are some examples of sending events :
+
```javascript
unomiTracker.page() // first call will be ignored as the initial page load is
done in the initialize method
@@ -62,3 +106,6 @@ unomiTracker.track('articleCompleted', {
});
```
+
+As the Unomi Tracker uses the Analytics.JS API, you can find more information
about it [here](https://segment.com/docs/sources/website/analytics.js/).
+All methods can be used on `unomiTracker` object, although not all event types
are supported by Unomi integration.
diff --git a/manual/src/main/asciidoc/web-tracker.adoc
b/manual/src/main/asciidoc/web-tracker.adoc
index 349193b..ecb1547 100644
--- a/manual/src/main/asciidoc/web-tracker.adoc
+++ b/manual/src/main/asciidoc/web-tracker.adoc
@@ -45,8 +45,53 @@ Then you can use the test page to try your changes
`http://localhost:8181/tracke
==== Tracking page views
+In the initialize call, the tracker will generate an implicit page view event,
which by default will be populated with
+the following information:
+
+[source,javascript]
+----
+ window.digitalData.page = window.digitalData.page || {
+ path: location.pathname + location.hash,
+ pageInfo: {
+ pageName: document.title,
+ pageID : location.pathname + location.hash,
+ pagePath : location.pathname + location.hash,
+ destinationURL: location.href
+ }
+ }
+----
+
+Now if you want to provide your own custom page information for the initial
page view, you can simply do it like this:
+
+[source,`javascript]
+----
+ unomiTracker.initialize({
+ scope: 'myScope',
+ url: 'http://unomi:8181', // we use an empty URL to make it
relative to this page.
+ initialPageProperties: {
+ path: path,
+ pageInfo: {
+ destinationURL: location.href,
+ tags: ["tag1", "tag2", "tag3"],
+ categories: ["category1", "category2", "category3"]
+ },
+ interests: {
+ "interest1": 1,
+ "interest2": 2,
+ "interest3": 3
+ }
+ }
+ });
+----
+
+`
+
+Also note that the FIRST call to unomiTracker.page() will be IGNORED because
of this initial page view.This is the
+way that the Analytics.js library handles it.So make sure you are aware of
this when calling it.This is to avoid having
+two page views on a single call and to be compatible with old versions that
did use the explicit call.
+
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
+to a single page application.In order to generate a page view programmatically
from Javascript you can use code similar
to this :
[source]
@@ -105,8 +150,8 @@ object passed to the unomiTracker call. Default value :
page path
|===
-The `interests` object is basically list of interests with "weights" attached
to them. These interests will be accumulated
-in Apache Unomi on profiles to indicate growing interest over time for
specific topics. These are freely defined and
+The `interests` object is basically list of interests with "weights" attached
to them.These interests will be accumulated
+in Apache Unomi on profiles to indicate growing interest over time for
specific topics.These are freely defined and
will be accepted by Apache Unomi without needing to declare them previously
anywhere (the same is true for tags and
categories).
