DOCSEARCHbyAlgolia
Submit Docs

django-analytical Documentation

repository·main·Indexed 23 days ago

https://github.com/jazzband/django-analytical

An analytics service integration for Django projects that provides a unified interface to manage multiple analytics services. It allows developers to keep service-specific configuration and tracking code out of templates using general-purpose template tags and settings for user identification, internal IP exclusion, and provider-specific identities. Supported integrations include Chartbeat, Clickmap, and Clicky.

Tokens
19.7K
Snippets
95
Records
136
Agent score
77%

What's inside django-analytical

  1. Overview of django-analytical

    main
    django-analytical is a Django application that integrates various analytics services into your project. It provides a generic interface that hides the specific implementation details and unique identifiers of different services, preventing sensitive configuration and service-specific JavaScript from cluttering your Django templates. The goal is to simplify basic setup while allowing advanced customization of tracking, typically using asynchronous JavaScript where possible.

  2. Override UserVoice configuration in views or context processors

    main

    You can override the global UserVoice configuration on a per-view or per-request basis using template context variables. These variables take precedence over the settings in settings.py.

    Per-view overrides

    In your view, add the following to the context:

    • uservoice_widget_options: A dictionary of UserVoice options.
    • uservoice_widget_key: A specific widget key string.
    • uservoice_add_trigger: A boolean to enable or disable the automatic trigger (e.g., False to hide the default icon/tab).

    Context processor overrides

    You can use a context processor to dynamically set the uservoice_widget_key based on the request (e.g., showing a different widget to authenticated users).

    # Example: Per-view override
context = RequestContext({'uservoice_widget_options': 'mode': 'satisfaction'})
return some_template.render(context)

# Example: Context processor for dynamic keys
def uservoice_widget_key(request):
    try:
        if request.user.is_authenticated():
            return {'uservoice_widget_key': 'XXXXXXXXXXXXXXXXXXXX'}
    except AttributeError:
        pass
    return {}

  3. Identify authenticated users in analytics

    main

    The django-analytical template tags can automatically identify and track authenticated users in services that support this feature (like Clicky).

    For this to work, the template context must contain the current user in either the user or request.user context variable. If you are using standard Django RequestContext and have django.contrib.auth.context_processors.auth in your TEMPLATE_CONTEXT_PROCESSORS setting (which is the default), no additional configuration is required.

  4. Exclude internal IP addresses from Intercom tracking

    main

    By default, the Intercom tracking code is commented out if the client's IP address is found in the ANALYTICAL_INTERNAL_IPS setting. This prevents development or internal traffic from being tracked.

    ANALYTICAL_INTERNAL_IPS defaults to using Django's standard INTERNAL_IPS setting.

  5. Set identity for a specific provider

    main
    If you want to change the identity for only one specific analytics provider without affecting others, use a context variable named using the pattern [provider_module_name]_identity. Replace [provider_module_name] with the actual name of the provider module.

  7. Configure user tracking and identity

    main

    By default, Matomo identifies users based on their Django username if ANALYTICAL_AUTO_IDENTIFY is set to True (which is the default).

    To customize the identity or disable tracking, use the following context variables:

    • matomo_identity: Use this for Matomo-specific identity configuration.
    • analytical_identity: Use this for global identity configuration.

    Setting either to None will disable user tracking (though statistics will still be collected).

    # Matomo will identify this user as 'Guido van Rossum'
context = Context({
    'matomo_identity': request.user.get_full_name()
})

# Matomo will not identify this user (but will still collect statistics)
context = Context({
    'matomo_identity': None
})

  9. Identify users in Mixpanel

    main

    By default, django-analytical automatically passes the username of an authenticated user to Mixpanel.

    To provide a custom identity, you can add either mixpanel_identity or analytical_identity to your template context. If both are present, mixpanel_identity takes precedence.

    To send additional user properties (using Mixpanel's people.set functionality), pass a dictionary to mixpanel_identity instead of a string. The dictionary must include a key named id or username to serve as the unique user ID; all other key-value pairs will be sent as people properties.

    # Example: Using a context processor to send identity and properties
def identify(request):
    try:
        return {
            'mixpanel_identity': {
                'id': request.user.id,
                'last_login': str(request.user.last_login),
                'date_joined': str(request.user.date_joined),
            }
        }
    except AttributeError:
        return {}

  10. Pass custom data to Woopra via template context

    main

    You can pass custom data to Woopra by including variables in your template context. Any context variable prefixed with woopra_ will be passed to the service.

    Commonly used variables include:

    • woopra_name: The visitor's full name.
    • woopra_email: The visitor's email address.
    • woopra_avatar: A URL link to a visitor avatar.

    You can set these in a view's RequestContext or via a context processor.

    # Example: Setting custom data in a view
context = RequestContext({'woopra_cart_value': cart.total_price})
return some_template.render(context)

  11. Add analytical template tags to your base template

    main

    To render the JavaScript required by your configured analytics services, add the analytical template tags to your base HTML template. You can use four general-purpose tags to place code in the head or body sections. This ensures that all enabled services are correctly integrated into the page lifecycle.

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

        ...

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

        ...

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

  12. Install the Hotjar integration

    main

    To use Hotjar with django-analytical, ensure the analytical application is added to your INSTALLED_APPS in settings.py.

    If you are not using the generic analytical.* template tags, you must explicitly load and use the hotjar template tag library in your templates. It is recommended to add the {% hotjar %} tag to the bottom of the <head> section in your base template to ensure all pages are tracked.

    {% load hotjar %}
<html>
<head>
...
{% hotjar %}
</head>
...
</html>