django-analytical/docs/install.rst

==============================
Installation and configuration
==============================

Integration of your analytics service is very simple.  There are four
steps: installing the package, adding it to the list of installed Django
applications, adding the template tags to your base template, and
configuring the services you use in the project settings.

#. `Installing the Python package`_
#. `Installing the Django application`_
#. `Adding the template tags to the base template`_
#. `Enabling the services`_


.. _installing-the-package:

Installing the Python package
=============================

To install django-analytical the ``analytical`` package must be added to
the Python path.  You can install it directly from PyPI using
``easy_install``:

.. code-block:: bash

    $ easy_install django-analytical

You can also install directly from source.  Download either the latest
stable version from PyPI_ or any release from GitHub_, or use Git to
get the development code:

.. code-block:: bash

    $ git clone https://github.com/jazzband/django-analytical.git

.. _PyPI: http://pypi.python.org/pypi/django-analytical/
.. _GitHub: http://github.com/jazzband/django-analytical

Then install the package by running the setup script:

.. code-block:: bash

    $ cd django-analytical
    $ python setup.py install


.. _installing-the-application:

Installing the Django application
=================================

After you installed django-analytical, add the ``analytical`` Django
application to the list of installed applications in the ``settings.py``
file of your project:

.. code-block:: python

    INSTALLED_APPS = [
        ...
        'analytical',
        ...
    ]


.. _adding-the-template-tags:

Adding the template tags to the base template
=============================================

Because every analytics service uses own specific Javascript code that
should be added to the top or bottom of either the head or body of the
HTML page, django-analytical provides four general-purpose template tags
that will render the code needed for the services you are using.  Your
base template should look like this:

.. code-block:: django

    {% load analytical %}
    <!DOCTYPE ... >
    <html>
        <head>
            {% analytical_head_top %}

            ...

            {% analytical_head_bottom %}
        </head>
        <body>
            {% analytical_body_top %}

            ...

            {% analytical_body_bottom %}
        </body>
    </html>

Instead of using the generic tags, you can also just use tags specific
for the analytics service(s) you are using.  See :ref:`services` for
documentation on using individual services.


.. _enabling-services:

Enabling the services
=====================

Without configuration, the template tags all render the empty string.
Services are configured in the project ``settings.py`` file.  The
settings required to enable each service are listed here:

* :doc:`Chartbeat <services/chartbeat>`::

    CHARTBEAT_USER_ID = '12345'

* :doc:`Clickmap <services/clickmap>`::

    CLICKMAP_TRACKER_CODE = '12345678....912'

* :doc:`Clicky <services/clicky>`::

    CLICKY_SITE_ID = '12345678'

* :doc:`Crazy Egg <services/crazy_egg>`::

    CRAZY_EGG_ACCOUNT_NUMBER = '12345678'

* :doc:`Facebook Pixel <services/facebook_pixel>`::

    FACEBOOK_PIXEL_ID = '1234567890'

* :doc:`Gaug.es <services/gauges>`::

    GAUGES_SITE_ID = '0123456789abcdef0123456789abcdef'

* :doc:`Google Analytics (legacy) <services/google_analytics>`::

    GOOGLE_ANALYTICS_PROPERTY_ID = 'UA-1234567-8'

* :doc:`Google Analytics (gtag.js) <services/google_analytics_gtag>`::

    GOOGLE_ANALYTICS_GTAG_PROPERTY_ID = 'UA-1234567-8'

* :doc:`Google Analytics (analytics.js) <services/google_analytics_js>`::

    GOOGLE_ANALYTICS_JS_PROPERTY_ID = 'UA-12345678-9'

* :doc:`HubSpot <services/hubspot>`::

    HUBSPOT_PORTAL_ID = '1234'
    HUBSPOT_DOMAIN = 'somedomain.web101.hubspot.com'

* :doc:`Intercom <services/intercom>`::

    INTERCOM_APP_ID = '0123456789abcdef0123456789abcdef01234567'

* :doc:`KISSinsights <services/kiss_insights>`::

    KISS_INSIGHTS_ACCOUNT_NUMBER = '12345'
    KISS_INSIGHTS_SITE_CODE = 'abc'

* :doc:`KISSmetrics <services/kiss_metrics>`::

    KISS_METRICS_API_KEY = '0123456789abcdef0123456789abcdef01234567'

* :doc:`Matomo (formerly Piwik) <services/matomo>`::

    MATOMO_DOMAIN_PATH = 'your.matomo.server/optional/path'
    MATOMO_SITE_ID = '123'

* :doc:`Mixpanel <services/mixpanel>`::

    MIXPANEL_API_TOKEN = '0123456789abcdef0123456789abcdef'

* :doc:`Olark <services/olark>`::

    OLARK_SITE_ID = '1234-567-89-0123'

* :doc:`Optimizely <services/optimizely>`::

    OPTIMIZELY_ACCOUNT_NUMBER = '1234567'

* :doc:`Performable <services/performable>`::

    PERFORMABLE_API_KEY = '123abc'

* :doc:`Piwik (deprecated, see Matomo) <services/piwik>`::

    PIWIK_DOMAIN_PATH = 'your.piwik.server/optional/path'
    PIWIK_SITE_ID = '123'

* :doc:`Rating\@Mail.ru <services/rating_mailru>`::

    RATING_MAILRU_COUNTER_ID = '1234567'

* :doc:`SnapEngage <services/snapengage>`::

    SNAPENGAGE_WIDGET_ID = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

* :doc:`Woopra <services/woopra>`::

    WOOPRA_DOMAIN = 'abcde.com'

* :doc:`Yandex.Metrica <services/yandex_metrica>`::

    YANDEX_METRICA_COUNTER_ID = '12345678'

----

The django-analytical application is now set-up to track visitors.  For
information about identifying users, further configuration and
customization, see :doc:`features`.
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00			`==============================`
			`Installation and configuration`
			`==============================`
Create project 2011-01-21 01:01:40 +00:00
			`Integration of your analytics service is very simple. There are four`
			`steps: installing the package, adding it to the list of installed Django`
Simplify analytics tag loading The general-purpose tag loading code was much too generic and complex, so this commit hard-codes the supported services. Also adds a tutorial to the documentation. This commit is not tested. 2011-01-28 17:01:09 +00:00			`applications, adding the template tags to your base template, and`
			`configuring the services you use in the project settings.`
Create project 2011-01-21 01:01:40 +00:00
			#. `Installing the Python package`_
			#. `Installing the Django application`_
			#. `Adding the template tags to the base template`_
Update documentation This commit finishes up the tutorial. It also fixes the individual service documentation and documents the service-specific / global analytical settings and context variables. 2011-01-29 07:04:51 +00:00			#. `Enabling the services`_
Create project 2011-01-21 01:01:40 +00:00

Simplify analytics tag loading The general-purpose tag loading code was much too generic and complex, so this commit hard-codes the supported services. Also adds a tutorial to the documentation. This commit is not tested. 2011-01-28 17:01:09 +00:00			`.. _installing-the-package:`

Create project 2011-01-21 01:01:40 +00:00			`Installing the Python package`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00			`=============================`
Create project 2011-01-21 01:01:40 +00:00
			To install django-analytical the ``analytical`` package must be added to
			`the Python path. You can install it directly from PyPI using`
Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			``easy_install``:
Create project 2011-01-21 01:01:40 +00:00
Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`.. code-block:: bash`

			`$ easy_install django-analytical`
Create project 2011-01-21 01:01:40 +00:00
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00			`You can also install directly from source. Download either the latest`
Create project 2011-01-21 01:01:40 +00:00			`stable version from PyPI_ or any release from GitHub_, or use Git to`
Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`get the development code:`

			`.. code-block:: bash`
Create project 2011-01-21 01:01:40 +00:00
Change all links from .../jcassee/d-a to jazzband 2018-11-28 20:36:23 +00:00			`$ git clone https://github.com/jazzband/django-analytical.git`
Create project 2011-01-21 01:01:40 +00:00
			`.. _PyPI: http://pypi.python.org/pypi/django-analytical/`
Change all links from .../jcassee/d-a to jazzband 2018-11-28 20:36:23 +00:00			`.. _GitHub: http://github.com/jazzband/django-analytical`
Create project 2011-01-21 01:01:40 +00:00
Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`Then install the package by running the setup script:`

Fix Sphinx warning about code-block in install.rst 2016-05-25 08:43:57 +00:00			`.. code-block:: bash`
Create project 2011-01-21 01:01:40 +00:00
Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`$ cd django-analytical`
			`$ python setup.py install`
Create project 2011-01-21 01:01:40 +00:00

Simplify analytics tag loading The general-purpose tag loading code was much too generic and complex, so this commit hard-codes the supported services. Also adds a tutorial to the documentation. This commit is not tested. 2011-01-28 17:01:09 +00:00			`.. _installing-the-application:`

Create project 2011-01-21 01:01:40 +00:00			`Installing the Django application`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00			`=================================`
Create project 2011-01-21 01:01:40 +00:00
Simplify analytics tag loading The general-purpose tag loading code was much too generic and complex, so this commit hard-codes the supported services. Also adds a tutorial to the documentation. This commit is not tested. 2011-01-28 17:01:09 +00:00			After you installed django-analytical, add the ``analytical`` Django
Create project 2011-01-21 01:01:40 +00:00			application to the list of installed applications in the ``settings.py``
Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`file of your project:`
Create project 2011-01-21 01:01:40 +00:00
Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`.. code-block:: python`

			`INSTALLED_APPS = [`
			`...`
			`'analytical',`
			`...`
			`]`
Create project 2011-01-21 01:01:40 +00:00

Simplify analytics tag loading The general-purpose tag loading code was much too generic and complex, so this commit hard-codes the supported services. Also adds a tutorial to the documentation. This commit is not tested. 2011-01-28 17:01:09 +00:00			`.. _adding-the-template-tags:`

Create project 2011-01-21 01:01:40 +00:00			`Adding the template tags to the base template`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00			`=============================================`
Create project 2011-01-21 01:01:40 +00:00
Simplify analytics tag loading The general-purpose tag loading code was much too generic and complex, so this commit hard-codes the supported services. Also adds a tutorial to the documentation. This commit is not tested. 2011-01-28 17:01:09 +00:00			`Because every analytics service uses own specific Javascript code that`
			`should be added to the top or bottom of either the head or body of the`
			`HTML page, django-analytical provides four general-purpose template tags`
			`that will render the code needed for the services you are using. Your`
Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`base template should look like this:`

Use code-block directive for snippets Correct spacing between sentences. Update URLs (http -> https) 2017-01-29 20:55:27 +00:00			`.. code-block:: django`
Create project 2011-01-21 01:01:40 +00:00
Use code-block directive for snippets Correct spacing between sentences. Update URLs (http -> https) 2017-01-29 20:55:27 +00:00			`{% load analytical %}`
			`<!DOCTYPE ... >`
			`<html>`
			`<head>`
			`{% analytical_head_top %}`
Create project 2011-01-21 01:01:40 +00:00
Use code-block directive for snippets Correct spacing between sentences. Update URLs (http -> https) 2017-01-29 20:55:27 +00:00			`...`
Create project 2011-01-21 01:01:40 +00:00
Use code-block directive for snippets Correct spacing between sentences. Update URLs (http -> https) 2017-01-29 20:55:27 +00:00			`{% analytical_head_bottom %}`
			`</head>`
			`<body>`
			`{% analytical_body_top %}`
Create project 2011-01-21 01:01:40 +00:00
Use code-block directive for snippets Correct spacing between sentences. Update URLs (http -> https) 2017-01-29 20:55:27 +00:00			`...`
Create project 2011-01-21 01:01:40 +00:00
Use code-block directive for snippets Correct spacing between sentences. Update URLs (http -> https) 2017-01-29 20:55:27 +00:00			`{% analytical_body_bottom %}`
			`</body>`
			`</html>`
Create project 2011-01-21 01:01:40 +00:00
Update documentation This commit finishes up the tutorial. It also fixes the individual service documentation and documents the service-specific / global analytical settings and context variables. 2011-01-29 07:04:51 +00:00			`Instead of using the generic tags, you can also just use tags specific`
			for the analytics service(s) you are using. See :ref:`services` for
			`documentation on using individual services.`
Simplify analytics tag loading The general-purpose tag loading code was much too generic and complex, so this commit hard-codes the supported services. Also adds a tutorial to the documentation. This commit is not tested. 2011-01-28 17:01:09 +00:00

Update documentation This commit finishes up the tutorial. It also fixes the individual service documentation and documents the service-specific / global analytical settings and context variables. 2011-01-29 07:04:51 +00:00			`.. _enabling-services:`
Create project 2011-01-21 01:01:40 +00:00
Update documentation This commit finishes up the tutorial. It also fixes the individual service documentation and documents the service-specific / global analytical settings and context variables. 2011-01-29 07:04:51 +00:00			`Enabling the services`
			`=====================`
Create project 2011-01-21 01:01:40 +00:00
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00			`Without configuration, the template tags all render the empty string.`
Update documentation This commit finishes up the tutorial. It also fixes the individual service documentation and documents the service-specific / global analytical settings and context variables. 2011-01-29 07:04:51 +00:00			Services are configured in the project ``settings.py`` file. The
			`settings required to enable each service are listed here:`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00
Add docs on identification 2011-01-25 00:13:19 +00:00			* :doc:`Chartbeat <services/chartbeat>`::

Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`CHARTBEAT_USER_ID = '12345'`
Add docs on identification 2011-01-25 00:13:19 +00:00
Initial integration of Clickmap into django-analytical. Basically working but tests and documentation is missing currently. 2012-12-05 07:22:17 +00:00			* :doc:`Clickmap <services/clickmap>`::

Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`CLICKMAP_TRACKER_CODE = '12345678....912'`
Initial integration of Clickmap into django-analytical. Basically working but tests and documentation is missing currently. 2012-12-05 07:22:17 +00:00
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00			* :doc:`Clicky <services/clicky>`::

Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`CLICKY_SITE_ID = '12345678'`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00
			* :doc:`Crazy Egg <services/crazy_egg>`::

Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`CRAZY_EGG_ACCOUNT_NUMBER = '12345678'`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00
Add initial Facebook Pixel docs 2017-10-17 14:46:14 +00:00			* :doc:`Facebook Pixel <services/facebook_pixel>`::

			`FACEBOOK_PIXEL_ID = '1234567890'`

added support for gaug.es 2012-02-24 23:14:17 +00:00			* :doc:`Gaug.es <services/gauges>`::

Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`GAUGES_SITE_ID = '0123456789abcdef0123456789abcdef'`
added support for gaug.es 2012-02-24 23:14:17 +00:00
Add missing Google Analytics instructions to install section 2020-12-05 13:18:18 +00:00			* :doc:`Google Analytics (legacy) <services/google_analytics>`::
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00
Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`GOOGLE_ANALYTICS_PROPERTY_ID = 'UA-1234567-8'`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00
Add missing Google Analytics instructions to install section 2020-12-05 13:18:18 +00:00			* :doc:`Google Analytics (gtag.js) <services/google_analytics_gtag>`::

			`GOOGLE_ANALYTICS_GTAG_PROPERTY_ID = 'UA-1234567-8'`

			* :doc:`Google Analytics (analytics.js) <services/google_analytics_js>`::

			`GOOGLE_ANALYTICS_JS_PROPERTY_ID = 'UA-12345678-9'`

Update documentation This commit finishes up the tutorial. It also fixes the individual service documentation and documents the service-specific / global analytical settings and context variables. 2011-01-29 07:04:51 +00:00			* :doc:`HubSpot <services/hubspot>`::

			`HUBSPOT_PORTAL_ID = '1234'`
			`HUBSPOT_DOMAIN = 'somedomain.web101.hubspot.com'`

Adds intercom.io support, fixes inconsent fails from json ordering. 2014-04-25 17:46:30 +00:00			* :doc:`Intercom <services/intercom>`::

			`INTERCOM_APP_ID = '0123456789abcdef0123456789abcdef01234567'`

Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00			* :doc:`KISSinsights <services/kiss_insights>`::

Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`KISS_INSIGHTS_ACCOUNT_NUMBER = '12345'`
			`KISS_INSIGHTS_SITE_CODE = 'abc'`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00
			* :doc:`KISSmetrics <services/kiss_metrics>`::

Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`KISS_METRICS_API_KEY = '0123456789abcdef0123456789abcdef01234567'`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00
Create Matomo module; leave Piwik to be deprecated With the rebranding of Piwik to Matomo, this commit: * copies the piwik module to matomo and rebrands * notes that the piwik module is deprecated * updates the javascript to the current Matomo version Implements #132 2019-04-06 21:55:12 +00:00			* :doc:`Matomo (formerly Piwik) <services/matomo>`::

			`MATOMO_DOMAIN_PATH = 'your.matomo.server/optional/path'`
			`MATOMO_SITE_ID = '123'`

Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00			* :doc:`Mixpanel <services/mixpanel>`::

Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`MIXPANEL_API_TOKEN = '0123456789abcdef0123456789abcdef'`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00
Add Olark and Reinvigorate to the install docs 2011-03-15 11:58:52 +00:00			* :doc:`Olark <services/olark>`::

			`OLARK_SITE_ID = '1234-567-89-0123'`

Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00			* :doc:`Optimizely <services/optimizely>`::

Fix some white space and highlighting in docs 2016-05-18 22:14:08 +00:00			`OPTIMIZELY_ACCOUNT_NUMBER = '1234567'`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00
Fix various documentation typos and missing text 2011-02-11 13:59:56 +00:00			* :doc:`Performable <services/performable>`::

			`PERFORMABLE_API_KEY = '123abc'`

Create Matomo module; leave Piwik to be deprecated With the rebranding of Piwik to Matomo, this commit: * copies the piwik module to matomo and rebrands * notes that the piwik module is deprecated * updates the javascript to the current Matomo version Implements #132 2019-04-06 21:55:12 +00:00			* :doc:`Piwik (deprecated, see Matomo) <services/piwik>`::
Added Piwik open source web analytics 2014-07-04 19:31:46 +00:00
			`PIWIK_DOMAIN_PATH = 'your.piwik.server/optional/path'`
			`PIWIK_SITE_ID = '123'`

Escape the '@' symbol in doc 2016-05-25 22:47:04 +00:00			* :doc:`Rating\@Mail.ru <services/rating_mailru>`::
Add support for the Raiting@Mail.ru service 2016-04-24 09:15:36 +00:00
			`RATING_MAILRU_COUNTER_ID = '1234567'`

Add SnapEngage details to Installation section Fixes #166 2020-11-13 17:03:02 +00:00			* :doc:`SnapEngage <services/snapengage>`::

			`SNAPENGAGE_WIDGET_ID = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'`

Add support for the Woopra service Also bump the version to 0.7.0. 2011-03-15 15:45:14 +00:00			* :doc:`Woopra <services/woopra>`::

			`WOOPRA_DOMAIN = 'abcde.com'`

Add support for the Yandex.Metrica service 2016-04-03 09:12:19 +00:00			* :doc:`Yandex.Metrica <services/yandex_metrica>`::

			`YANDEX_METRICA_COUNTER_ID = '12345678'`

Update documentation This commit finishes up the tutorial. It also fixes the individual service documentation and documents the service-specific / global analytical settings and context variables. 2011-01-29 07:04:51 +00:00			`----`
Updated analytical * Added Chartbeat. * Added settings context processor. * Added identification. * Prepared events. * Updated tests. 2011-01-24 23:13:44 +00:00
Fix name: django-analytics -> django-analytical 2012-08-13 10:30:47 +00:00			`The django-analytical application is now set-up to track visitors. For`
Add note on identifying users in installation docs 2012-10-18 07:39:31 +00:00			`information about identifying users, further configuration and`
			customization, see :doc:`features`.