A Django package to integrate Google Analytics seamlessly.

Project description

Google Analytics Django

A comprehensive Django package for seamless integration of Google Analytics into your Django projects, supporting Google Analytics 4 (GA4).

Features

Support for Universal Analytics (analytics.js) and Google Analytics 4 (gtag.js)
Configurable options for anonymizing IP, cookie expiration, sampling rates, and more
Middleware for setting custom headers and server-side tracking
Debug mode to prevent tracking in development environments
Automatic exclusion of staff users from tracking
Easy-to-use template tags for quick integration
Extensive settings for fine-grained control over tracking behavior
Event tracking and custom dimension/metric support

Installation

Install the package using pip:

pip install google-analytics-django

Add 'google_analytics_django' to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = [
    # ...
    'google_analytics_django',
    # ...
]

Add the middleware to your MIDDLEWARE in settings.py:

MIDDLEWARE = [
    # ...
    'google_analytics_django.middleware.GoogleAnalyticsMiddleware',
    # ...
]

Configuration

Add the following settings to your Django project's settings.py file:

# Required
GOOGLE_ANALYTICS_PROPERTY_ID = 'UA-XXXXXXXX-X'  # or 'G-XXXXXXXXXX' for GA4

# Optional (shown with default values)
GOOGLE_ANALYTICS_DOMAIN = 'auto'
GOOGLE_ANALYTICS_ANONYMIZE_IP = False
GOOGLE_ANALYTICS_SAMPLE_RATE = 100
GOOGLE_ANALYTICS_SITE_SPEED_SAMPLE_RATE = 1
GOOGLE_ANALYTICS_COOKIE_EXPIRES = 63072000  # 2 years in seconds
GOOGLE_ANALYTICS_DISPLAY_FEATURES = False
GOOGLE_ANALYTICS_USE_GTAG = True  # Set to False to use analytics.js
GOOGLE_ANALYTICS_DEBUG_MODE = False

Usage

Template Tag

In your base template, load the template tags and add the Google Analytics script:

{% load google_analytics_tags %}
<head>
    <!-- ... other head elements ... -->
    {% google_analytics %}
</head>

Middleware

The middleware is automatically active once added to your MIDDLEWARE setting. It adds two custom headers to the response:

X-GA-TRACKING-ID: The Google Analytics client ID (if available)
X-CLIENT-IP: The client's IP address

These headers can be used for server-side tracking if needed.

Advanced Features

Debug Mode

Set GOOGLE_ANALYTICS_DEBUG_MODE = True in your settings to prevent tracking in development environments.

Staff Exclusion

By default, staff users (users with is_staff=True) are not tracked. You can modify this behavior in the should_track function in utils.py.

Event Tracking

Use the standard Google Analytics JavaScript API to track events:

gtag("event", "button_click", {
  event_category: "engagement",
  event_label: "hero_cta",
});

Custom Dimensions and Metrics

Set up custom dimensions and metrics in your Google Analytics property, then use them in your tracking code:

gtag("config", "UA-XXXXXXXX-X", {
  custom_map: { dimension1: "user_type" },
});
gtag("event", "page_view", { user_type: "member" });

Troubleshooting

If you encounter issues:

Check that your GOOGLE_ANALYTICS_PROPERTY_ID is correct.
Ensure the middleware is properly added to your MIDDLEWARE setting.
Verify that the template tag is correctly placed in your base template.
Check browser console for any JavaScript errors.

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a new branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please ensure your code adheres to the project's coding standards and include tests for new features.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you need help or have any questions, please open an issue on the GitHub repository or contact the maintainers.

Project details

Release history Release notifications | RSS feed

This version

0.1.4

Nov 6, 2024

0.1.3

Nov 6, 2024

0.1.2

Nov 5, 2024

0.1.1

Nov 5, 2024

0.1.0

Oct 17, 2024

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

google_analytics_django-0.1.4.tar.gz (10.7 kB view details)

Uploaded Nov 6, 2024 Source

Built Distribution

google_analytics_django-0.1.4-py3-none-any.whl (10.2 kB view details)

Uploaded Nov 6, 2024 Python 3

File details

Details for the file google_analytics_django-0.1.4.tar.gz.

File metadata

Download URL: google_analytics_django-0.1.4.tar.gz
Upload date: Nov 6, 2024
Size: 10.7 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/5.1.1 CPython/3.12.1

File hashes

Hashes for google_analytics_django-0.1.4.tar.gz
Algorithm	Hash digest
SHA256	`8d649d6c38ead6b7f5c96192a8728937791d9d1c6d147f76639ea3f7abe2ea4b`
MD5	`789d08807ba9a83e181a4d15b10dd033`
BLAKE2b-256	`0e611ad59e2e540cf3e877d783a2fade990e32890e6ba9052701a09254a4cdf7`

See more details on using hashes here.

File details

Details for the file google_analytics_django-0.1.4-py3-none-any.whl.

File metadata

Download URL: google_analytics_django-0.1.4-py3-none-any.whl
Upload date: Nov 6, 2024
Size: 10.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/5.1.1 CPython/3.12.1

File hashes

Hashes for google_analytics_django-0.1.4-py3-none-any.whl
Algorithm	Hash digest
SHA256	`809e919dd00777562c58ef34b18d931ff5e465b3b3ea4972dfa9be41f806eca3`
MD5	`26978683980cdb9fb44496fa6faf56a0`
BLAKE2b-256	`e62e1b513c4b5bb00089b51be42d36d124d993978398ce8b3a968b8298e875b2`