django-smalk-tracker

Overview

The django-smalk-tracker is a Django package that provides server-side tracking for Smalk.ai. It includes a middleware that automatically tracks page views and user interactions, sending the data to your Smalk analytics service.

Features

• Easy integration with Django projects
• Configurable URL patterns for tracking
• Lightweight and performant
• Asynchronous tracking requests
• Comprehensive error handling
• Support for Django 3.2+ and Python 3.7+

Installation

Install using pip:

pip install django-smalk-tracker

Quick Start

1. Add 'smalk_tracker' to your INSTALLED_APPS setting:

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

2. Add the middleware to your MIDDLEWARE setting:

MIDDLEWARE = [
    # ...
    'smalk_tracker.middleware.SmalkServerSideTrackingMiddleware',
    # ...
]

3. Add your Smalk API key to settings.py: Generate the API key in your Smalk dashboard: https://app.smalk.ai/settings/api-keys

# Required
SMALK_PROJECT_API_KEY = "your-api-key-here"

Configuration

Required Settings

• SMALK_PROJECT_API_KEY (str): Your Smalk project API key. Get this from your Smalk dashboard.

Optional Settings

• SMALK_DISABLE_TRACKING (bool): Set to True to disable all tracking (default: False)
• SMALK_TRACKING_ALLOWED_PATH (list): List of URL paths to track (if not set, all paths are tracked)
• SMALK_TRACKING_EXCLUDE_URLS_REGEXES (list): List of regex patterns to exclude from tracking
• SMALK_DEFAULT_TIMEOUT (float): Request timeout in seconds (default: 0.15)
• SMALK_VISIT_URL (str): Override the default tracking endpoint URL
• SMALK_BOT_USER_AGENT (str): User agent string for the tracking requests

Default Excluded Paths

By default, the following paths are excluded from tracking:

• /api/* - All API endpoints
• /admin/* - Django admin interface
• /health/ - Health check endpoints
• *.js, *.css, *.png, *.jpg, *.jpeg, *.gif, *.ico - Static files

Example Configuration

# settings.py

# Required
SMALK_PROJECT_API_KEY = "your-api-key-here"

# Optional configuration
SMALK_DISABLE_TRACKING = False  # Set to True to disable tracking
SMALK_DEFAULT_TIMEOUT = 0.2  # 200ms

# Only track these paths (if not set, all paths are tracked)
SMALK_TRACKING_ALLOWED_PATH = [
    "/blog/",
    "/products/"
]

# Exclude these URL patterns from tracking
SMALK_TRACKING_EXCLUDE_URLS_REGEXES = [
    r"^/api/.*$",
    r"^/admin/.*$",
    r"^/private/.*$",
    r"^/health/.*$"
]

# Customize the tracking endpoint (optional)
# SMALK_VISIT_URL = "https://your-custom-endpoint.example.com/track"

# Customize the user agent (optional)
# SMALK_BOT_USER_AGENT = "YourApp/1.0"

How It Works

1. For each incoming request, the middleware checks if tracking should be performed based on:

   • If tracking is disabled via SMALK_DISABLE_TRACKING
   • If the request path matches any allowed paths (if SMALK_TRACKING_ALLOWED_PATH is set)
   • If the request path doesn't match any excluded patterns
   • If the request is for a static file (images, CSS, JS, etc.)

2. If tracking is enabled for the request, it sends the following data to the Smalk tracking endpoint:

   • Request path
   • Request method
   • Request headers
   • Timestamp

3. The tracking request is made asynchronously with a configurable timeout to minimize impact on response times.

Error Handling

The middleware includes comprehensive error handling:

• Failed tracking requests are logged but don't affect the user experience
• Invalid configurations are logged at startup
• Network timeouts are handled gracefully
• All exceptions are caught and logged to prevent affecting the main application

Best Practices

1. Performance:

   • Keep the SMALK_DEFAULT_TIMEOUT low (100-300ms) to minimize impact on page load times
   • Use SMALK_TRACKING_ALLOWED_PATH to limit tracking to specific paths when possible

2. Security:

   • Be cautious when including sensitive information in request headers
   • Review the default exclusions and add any additional paths that might contain sensitive information

3. Development:

   • Set SMALK_DISABLE_TRACKING = True in your development settings
   • Monitor your logs for any tracking-related errors

4. Production:

   • Ensure SMALK_PROJECT_API_KEY is stored securely (e.g., environment variables)
   • Monitor the performance impact of tracking on your application

Troubleshooting

No tracking data is being sent

1. Check if SMALK_DISABLE_TRACKING is False
2. Verify SMALK_PROJECT_API_KEY is set correctly
3. Check if the request path is included in SMALK_TRACKING_ALLOWED_PATH (if set)
4. Look for any error messages in your application logs
5. Ensure the request path doesn't match any patterns in SMALK_TRACKING_EXCLUDE_URLS_REGEXES

Tracking requests are slow

1. Reduce the SMALK_DEFAULT_TIMEOUT value
2. Check your network connection to the Smalk API
3. Consider using a CDN or proxy if the Smalk API is geographically distant

Development

To contribute to this project:

1. Fork the repository
2. Create a virtual environment
3. Install development dependencies:

   pip install -e .[dev]

4. Run tests:

   python -m pytest

5. Submit a pull request

License

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

Support

For support, please open an issue on the GitHub repository or contact support@smalk.ai.