1 files changed, 133 insertions, 0 deletions
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
+
+
+*/