qt analytics initial importHEADdev

Change-Id: I2a0274b00f848d7eaf698ce3b68cf4f5dfd0a516
Reviewed-by: Vladimir Minenko <[email protected]>
Reviewed-by: Bramastyo Harimukti Santoso <[email protected]>

13 files changed, 575 insertions, 0 deletions

diff --git a/doc/doc.pri b/doc/doc.pri
new file mode 100644
index 0000000..eb311b0
--- /dev/null
+++ b/doc/doc.pri
@@ -0,0 +1,14 @@
+build_online_docs: {
+    QMAKE_DOCS_TARGETDIR = qtanalytics
+    QMAKE_DOCS = $$PWD/qtanalytics-online.qdocconf
+} else {
+    QMAKE_DOCS = $$PWD/qtanalytics.qdocconf
+}
+
+load(qt_docs_targets)
+
+OTHER_FILES += \
+    $$PWD/*.qdocconf \
+    $$PWD/*.qdoc \
+    $$PWD/examples/*.qdoc \
+    $$PWD/images/*.png
diff --git a/doc/doc.pro b/doc/doc.pro
new file mode 100644
index 0000000..46b9f9b
--- /dev/null
+++ b/doc/doc.pro
@@ -0,0 +1,19 @@
+TEMPLATE = aux
+
+CONFIG += force_qt
+QT *= quick network
+
+build_online_docs: {
+    QMAKE_DOCS_TARGETDIR = qtanalytics
+    QMAKE_DOCS = $$PWD/qtanalytics-online.qdocconf
+} else {
+    QMAKE_DOCS = $$PWD/qtanalytics.qdocconf
+}
+
+include(doc.pri)
+
+OTHER_FILES += \
+    $$PWD/*.qdocconf \
+    $$PWD/*.qdoc \
+    $$PWD/examples/*.qdoc \
+    $$PWD/images/*.png
diff --git a/doc/examples/analytics_demo.qdoc b/doc/examples/analytics_demo.qdoc
new file mode 100644
index 0000000..9afedb6
--- /dev/null
+++ b/doc/examples/analytics_demo.qdoc
@@ -0,0 +1,38 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Luxoft Sweden AB
+**
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAnalytics plugin.
+**
+** $QT_BEGIN_LICENSE:GPL-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite licenses may use
+** this file in accordance with the commercial license agreement provided
+** with the Software or, alternatively, in accordance with the terms
+** contained in a written agreement between you and The Qt Company.  For
+** licensing terms and conditions see https://www.qt.io/terms-conditions.
+** For further information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 or (at your option) any later version
+** approved by the KDE Free Qt Foundation. The licenses are as published by
+** the Free Software Foundation and appearing in the file LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+** SPDX-License-Identifier: GPL-3.0
+**
+****************************************************************************/
+/*!
+    \example analytics_demo
+    \title Analytics Demo
+
+    \brief Demonstrates how to use the analytics plugin.
+
+*/
diff --git a/doc/index.qdoc b/doc/index.qdoc
new file mode 100644
index 0000000..d31b74e
--- /dev/null
+++ b/doc/index.qdoc
@@ -0,0 +1,59 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Luxoft Sweden AB
+**
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt analytics plugin.
+**
+** $QT_BEGIN_LICENSE:GPL-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite licenses may use
+** this file in accordance with the commercial license agreement provided
+** with the Software or, alternatively, in accordance with the terms
+** contained in a written agreement between you and The Qt Company.  For
+** licensing terms and conditions see https://www.qt.io/terms-conditions.
+** For further information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 or (at your option) any later version
+** approved by the KDE Free Qt Foundation. The licenses are as published by
+** the Free Software Foundation and appearing in the file LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+** SPDX-License-Identifier: GPL-3.0
+**
+****************************************************************************/
+
+/*!
+
+\page qtanalytics-index.html
+\keyword QtAnalytics Reference Documentation
+\title Qt Analytics
+
+\section1 Overview
+
+Qt analytics is a module to send user interface traces to a cloud server.
+
+ \list
+   \li \l{qtanalytics}{Qt Analytics}
+   \li \l{Concepts}
+   \li \l{Installation}
+   \li \l{Usage}
+ \endlist
+*/
+
+/*!
+ * \page qtanalytics-reference
+ * \title API Reference
+ *
+ *
+ * \list
+ *   \li \l{qtanalytics}{Qt Analytics}
+ * \endlist
+ */
diff --git a/doc/qtanalytics-concepts.qdoc b/doc/qtanalytics-concepts.qdoc
new file mode 100644
index 0000000..cf9c2a3
--- /dev/null
+++ b/doc/qtanalytics-concepts.qdoc
@@ -0,0 +1,133 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Luxoft Sweden AB
+**
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAnalytics plugin.
+**
+** $QT_BEGIN_LICENSE:GPL-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite licenses may use
+** this file in accordance with the commercial license agreement provided
+** with the Software or, alternatively, in accordance with the terms
+** contained in a written agreement between you and The Qt Company.  For
+** licensing terms and conditions see https://www.qt.io/terms-conditions.
+** For further information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 or (at your option) any later version
+** approved by the KDE Free Qt Foundation. The licenses are as published by
+** the Free Software Foundation and appearing in the file LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+** SPDX-License-Identifier: GPL-3.0
+**
+****************************************************************************/
+
+/*!
+
+\page qtanalytics-concepts.html
+\title Concepts
+
+\section1 Tracking
+
+What do we want to track?
+
+We want mostly track page views and actions, as also general device
+information.
+
+\section1 ConfigUtil
+
+\l ConfigUtil provides utility function to load and parse JSON based
+configuration files. The file lookup is based on a given name (e.g.
+\c {analytics}) and the lookup looks first for an environment variable
+called \c {ANALYTICS_CONFIG}, and if exists will take that path. If not
+then a file will be looked in the resource file named \c {:/analytics.json}.
+If this also not exists a warning is printed and the configuration is
+not successful.
+
+\section1 \l {Context} {Context}
+
+The \l Context object provides the methods available to the builders. It is
+reused across all hits. It provides a configuration value access as also network
+HTTP GET/POST methods.
+
+In general it should be possible to have a Context interface which could
+then be used inside the hit builders and by this making them more
+testable.
+
+The configuration is stored into a JSON file (e.g. analytics.json) which
+is looked up using the ConfigUtil functions.
+
+\sa {Context}, {IContext}
+
+\section1 \l {HitBuilder} {Hit Builder}
+
+The hit builder is an interface used to collect the various tracking
+information and then send the information away using a network.
+
+The hit builder has a common high level API to be shared across specific
+builders.
+
+\list
+\li send build trackVisit trackEvent
+\endlist
+
+\sa {HitBuilder}, {MatomoBuilder}, {GoogleBuilder}
+
+\section1 \l {MatomoBuilder} {Matomo Hit Builder}
+
+\list
+\li \l {https://developer.matomo.org/api-reference/tracking-api}
+\endlist
+
+The Matomo hit builder is enabled by setting tracker to "matomo" in the
+configuration file. The builder support visit and event tracking. It
+uses a GET request to the server URL to send the tracking information.
+
+\section1 \l {GoogleBuilder} {Google Analytics Tracking}
+
+\list
+\li \l {https://developers.google.com/analytics/devguides/collection/protocol/v1/}
+\li \l {https://ga-dev-tools.appspot.com/hit-builder/}
+\endlist
+
+The Google hit builder is enabled by setting the tracker to "google". It
+uses the Google measurements protocol.
+
+\section1 Configuration Format
+
+The configuration is stored in JSON documents. The document keys change with the chosen \c tracker (e.g. \c matomo, \c google).
+
+\note It is not possible currently to support several trackers.
+
+\section2 Google Configuration
+
+\code
+{
+    "tracker": "google"
+    "tid": "UA-555555555-5",
+    "cid": "555",
+    "deviceResolution": "1280x800",
+    "domain": "http://example.org/",
+}
+\endcode
+
+\section2 Matomo Configuration
+
+\code
+{
+    "tracker": "matomo",
+    "server": "http://localhost:8000/piwik.php",
+    "idsite": "1"
+}
+\endcode
+
+
+*/
diff --git a/doc/qtanalytics-examples.qdoc b/doc/qtanalytics-examples.qdoc
new file mode 100644
index 0000000..0b8f0e7
--- /dev/null
+++ b/doc/qtanalytics-examples.qdoc
@@ -0,0 +1,42 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Luxoft Sweden AB
+**
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAnalytics plugin.
+**
+** $QT_BEGIN_LICENSE:GPL-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite licenses may use
+** this file in accordance with the commercial license agreement provided
+** with the Software or, alternatively, in accordance with the terms
+** contained in a written agreement between you and The Qt Company.  For
+** licensing terms and conditions see https://www.qt.io/terms-conditions.
+** For further information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 or (at your option) any later version
+** approved by the KDE Free Qt Foundation. The licenses are as published by
+** the Free Software Foundation and appearing in the file LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+** SPDX-License-Identifier: GPL-3.0
+**
+****************************************************************************/
+
+/*!
+   \group qtanalytics-examples
+   \title Analytics Examples
+   \brief Examples showing how to extend the functionality of Qt Analytics.
+
+   \list
+    \li \l{qtanalytics_demo}{Analytics Demo}
+   \endlist
+
+*/
diff --git a/doc/qtanalytics-group.qdoc b/doc/qtanalytics-group.qdoc
new file mode 100644
index 0000000..a67c558
--- /dev/null
+++ b/doc/qtanalytics-group.qdoc
@@ -0,0 +1,46 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Luxoft Sweden AB
+**
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAnalytics plugin.
+**
+** $QT_BEGIN_LICENSE:GPL-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite licenses may use
+** this file in accordance with the commercial license agreement provided
+** with the Software or, alternatively, in accordance with the terms
+** contained in a written agreement between you and The Qt Company.  For
+** licensing terms and conditions see https://www.qt.io/terms-conditions.
+** For further information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 or (at your option) any later version
+** approved by the KDE Free Qt Foundation. The licenses are as published by
+** the Free Software Foundation and appearing in the file LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+** SPDX-License-Identifier: GPL-3.0
+**
+****************************************************************************/
+
+
+/*!
+    \module qtanalytics
+
+    \title Qt Analytics Module
+    \brief Classes for interacting with a Matomo server to track user
+    interface metrics.
+
+    The QtAnalytics module allows a developer to provide traces inside a user interface to send those ui traces to a Matamo server.
+
+    Tracing is limited currently to tracing page views, events and custom variables.
+    Traces are send to the server directly using a HTTP GET or POST request. There is support currently for the Matamo server and the Google Analytics platform.
+
+ */
diff --git a/doc/qtanalytics-installation.qdoc b/doc/qtanalytics-installation.qdoc
new file mode 100644
index 0000000..82e9f31
--- /dev/null
+++ b/doc/qtanalytics-installation.qdoc
@@ -0,0 +1,56 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Luxoft Sweden AB
+**
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAnalytics plugin.
+**
+** $QT_BEGIN_LICENSE:GPL-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite licenses may use
+** this file in accordance with the commercial license agreement provided
+** with the Software or, alternatively, in accordance with the terms
+** contained in a written agreement between you and The Qt Company.  For
+** licensing terms and conditions see https://www.qt.io/terms-conditions.
+** For further information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 or (at your option) any later version
+** approved by the KDE Free Qt Foundation. The licenses are as published by
+** the Free Software Foundation and appearing in the file LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+** SPDX-License-Identifier: GPL-3.0
+**
+****************************************************************************/
+
+/*!
+
+\page qtanalytics-installation.html
+\title Installation
+
+\section1 Dependencies
+
+\list
+    \li Windows, Linux or macOS
+    \li Qt5.4 or higher
+\endlist
+
+\section1 Building for desktop
+
+\code
+    $ qmake
+    $ make
+    $ make install
+\endcode
+
+Qt Analytics plugin is installed into the Qt SDK as a QtQuick plugin. See \l {Usage} for more information how to use the plugin.
+
+
+*/
diff --git a/doc/qtanalytics-online.qdocconf b/doc/qtanalytics-online.qdocconf
new file mode 100644
index 0000000..a8a4108
--- /dev/null
+++ b/doc/qtanalytics-online.qdocconf
@@ -0,0 +1,23 @@
+
+HTML.footer = \
+    "   </div>\n" \
+    "   <p class=\"copy-notice\">\n" \
+    "   <acronym title=\"Copyright\">&copy;</acronym> 2019 Luxoft Sweden AB.\n" \
+    "   Documentation contributions included herein are the copyrights of\n" \
+    "   their respective owners. " \
+    "   The documentation provided herein is licensed under the terms of the" \
+    "   <a href=\"http://www.gnu.org/licenses/fdl.html/">GNU Free Documentation" \
+    "   License version 1.3</a> as published by the Free Software Foundation. " \
+    "   Qt and respective logos are trademarks of The Qt Company Ltd. " \
+    "   in Finland and/or other countries worldwide. All other trademarks are property\n" \
+    "   of their respective owners. </p>\n"
+
+include($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf)
+
+# Add an .html file with sidebar content, used in the online style
+HTML.stylesheets               += style/qt5-sidebar.html
+
+HTML.nosubdirs = "false"
+HTML.outputsubdir = "qtanalytics"
+
+include(qtanalytics-project.qdocconf)
diff --git a/doc/qtanalytics-project.qdocconf b/doc/qtanalytics-project.qdocconf
new file mode 100644
index 0000000..6e8f7fe
--- /dev/null
+++ b/doc/qtanalytics-project.qdocconf
@@ -0,0 +1,42 @@
+project = QtAnalytics
+description = QtAnalytics Reference Documentation
+url = https://doc.qt.io/QtAnalytics
+version = $QT_VERSION
+
+sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
+headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
+
+examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml"
+examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"
+
+exampledirs = ../examples ../src
+
+headerdirs = \
+    ../src
+
+sourcedirs += \
+    . \
+    ../src \
+    ../examples
+
+imagedirs = images
+
+qhp.projects                    = QtAnalytics
+qhp.QtAnalytics.file                = qtanalytics.qhp
+qhp.QtAnalytics.namespace           = io.qt.qtanalytics.$QT_VERSION_TAG
+qhp.QtAnalytics.virtualFolder       = qtanalytics
+qhp.QtAnalytics.indexTitle          = Qt Analytics
+qhp.QtAnalytics.indexRoot           =
+
+qhp.QtAnalytics.filterAttributes = QtAnalytics $QT_VERSION
+qhp.QtAnalytics.customFilters.QtAnalytics.name = QtAnalytics $QT_VERSION
+qhp.QtAnalytics.customFilters.QtAnalytics.filterAttributes = QtAnalytics $QT_VERSION
+
+qhp.QtAnalytics.subprojects = manual
+qhp.QtAnalytics.subprojects.manual.title = Qt Analytics
+qhp.QtAnalytics.subprojects.manual.indexTitle = Qt Analytics
+qhp.QtAnalytics.subprojects.manual.type = manual
+
+navigation.homepage = "Qt Automotive Suite"
+navigation.landingpage = "Qt Analytics"
+buildversion = "Qt Analytics $QT_VERSION"
diff --git a/doc/qtanalytics-usage.qdoc b/doc/qtanalytics-usage.qdoc
new file mode 100644
index 0000000..8b6eb1b
--- /dev/null
+++ b/doc/qtanalytics-usage.qdoc
@@ -0,0 +1,69 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Luxoft Sweden AB
+**
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAnalytics plugin.
+**
+** $QT_BEGIN_LICENSE:GPL-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite licenses may use
+** this file in accordance with the commercial license agreement provided
+** with the Software or, alternatively, in accordance with the terms
+** contained in a written agreement between you and The Qt Company.  For
+** licensing terms and conditions see https://www.qt.io/terms-conditions.
+** For further information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 or (at your option) any later version
+** approved by the KDE Free Qt Foundation. The licenses are as published by
+** the Free Software Foundation and appearing in the file LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+** SPDX-License-Identifier: GPL-3.0
+**
+****************************************************************************/
+
+/*!
+
+\page qtanalytics-usage.html
+\title Usage
+
+\section1 Introduction
+
+The analytics plugin works with either a recent Matamo Server or Google Analytics. For both setup it is assumed the credentials and logins are available.
+
+To avoid having configuration information inside the UI code the plugin looks up a configuration file. The configuration is stored by default into a \c {:/analytics.json} document. This location can be overridden using the \c {ANALYTICS_CONFIG} environment variable.
+
+The config file must have at least a \c {tracker} key and the corresponding builder configuration.
+
+For example for a google tracker you specify
+
+\code
+{
+    "tracker": "google"
+    "tid": "UA-555555555-5",
+    "cid": "555",
+    "deviceResolution": "1280x800",
+    "domain": "http://example.org/",
+}
+\endcode
+
+\list
+\li \c tracker - the tracker backend to be used
+\li \c tid - the tracker id
+\li \c cid - the client id
+\li \c deviceResolution - a custom variable to be send with the tracker
+\li \c domain - the URI the application will identify
+\endlist
+
+
+See \l {Concepts} for more information.
+
+*/
diff --git a/doc/qtanalytics.qdocconf b/doc/qtanalytics.qdocconf
new file mode 100644
index 0000000..b094803
--- /dev/null
+++ b/doc/qtanalytics.qdocconf
@@ -0,0 +1,21 @@
+include($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf)
+include(qtanalytics-project.qdocconf)
+
+HTML.footer = \
+    "        </div>\n" \
+    "       </div>\n" \
+    "   </div>\n" \
+    "   </div>\n" \
+    "</div>\n" \
+    "<div class=\"footer\">\n" \
+    "   <p>\n" \
+    "   <acronym title=\"Copyright\">&copy;</acronym> 2019 Luxoft Sweden AB.\n" \
+    "   Documentation contributions included herein are the copyrights of\n" \
+    "   their respective owners.<br>" \
+    "   The documentation provided herein is licensed under the terms of the" \
+    "   <a href=\"http://www.gnu.org/licenses/fdl.html/">GNU Free Documentation" \
+    "   License version 1.3</a> as published by the Free Software Foundation.<br>" \
+    "   Qt and respective logos are trademarks of The Qt Company Ltd. " \
+    "   in Finland and/or other countries worldwide. All other trademarks are property\n" \
+    "   of their respective owners. </p>\n" \
+    "</div>\n"
diff --git a/doc/style/qt5-sidebar.html b/doc/style/qt5-sidebar.html
new file mode 100644
index 0000000..bb4f6b0
--- /dev/null
+++ b/doc/style/qt5-sidebar.html
@@ -0,0 +1,13 @@
+<div class="sectionlist normallist">
+    <div class="heading">
+        <h2>Qt Analytics</h2>
+    </div>
+    <ul>
+        <li><a href="http://code.qt.io/index.html">Home</a></li>
+        <li><a href="http://code.qt.io/qtanalytics-installation.html">Installation</a></li>
+        <li><a href="http://code.qt.io/qtanalytics-usage.html">Usage</a></li>
+        <li><a href="http://code.qt.io/qtanalytics-concepts.html">Concepts</a></li>
+        <li><a href="http://code.qt.io/qtanalytics-reference.html">Reference</a></li>
+        <li><a href="http://code.qt.io/qtanalytics-examples.html">Examples</a></li>
+    </ul>
+</div>