Skip to main content

Django module to proxy requests to Plausible Analytics.

Project description

Django Plausible Proxy

Django application to proxy requests and send server-side events to Plausible Analytics. Plays well with self-hosted and the managed cloud service.

Proxying

Proxying allows a project owner concerned about missing data seeing a more complete picture. See Adblockers and using a proxy for analytics for the detailed outline of the problem and solution.

When installed and configured in settings.py and urls.py, the app proxies the HTTP requests as such:

https://<yourdomain.com>/js/script.js -> https://plausible.io/js/script.js
https://<yourdomain.com>/api/event    -> https://plausible.io/api/event

Server-side events

Track on the server side events that can't be tracked otherwise, such as API requests.

from plausible_proxy import send_custom_event
...
send_custom_event(request, name="Register", props={"plan": "Premium"})

Installation

Install the package from PyPI.

pip install django-plausible-proxy

Configure Django setting in the settings.py.

# Register the app to enable {% plausble %} templatetag.
INSTALLED_APPS = [
    # ...
    "plausible_proxy"
    # ...
]

# Optionally, define a default value for Plausible domain to provide a default value
# for the Plausible domain and the `send_custom_event()` function.
PLAUSIBLE_DOMAIN = "yourdomain.com"

# Optionally, define the plausible endpoint that you would like to post to.
# This is useful if you are self-hosting plausible.
PLAUSIBLE_BASE_URL = "https://plausible.io"

# Optionally, define the value for the script prefix. The default value is "js". When
# you include the script to the page with the {% plausible %} templatetag, it becomes
# available as "<script src='${PLAUSIBLE_SCRIPT_PREFIX}/script.js'></script>". E.g.,
# "<script src='js/script.js'></script>"
#
# Overriding PLAUSIBLE_SCRIPT_PREFIX is helpful to avoid clashes with another script
# of your site that may become available under the same name.

PLAUSIBLE_SCRIPT_PREFIX = "plsbl/js"

# Optionally, provide a timeout for the connection to your plausible endpoint in
# seconds. Defaults to 1 second. Adjust to lower values in case you can't trust your
# infrastructure to consistently deliver low load times and you don't care as much
# about consistent analytics.
PLAUSIBLE_REQUEST_TIMEOUT = 1

Update urls.py.

from django.urls import include, path

urlpatterns = [
    # ...
    path("", include("plausible_proxy.urls")),
    # ...
]

Update your base HTML template to include the plausible templatetag.

{% load plausible %}
<html>
  <head>
      ...
      {% plausible script='script.js' %}
  </head>

API reference

{% plausible %}

A templatetag to include the Plausible analytics script to the page.

Arguments:

  • domain (default to settings.PLAUSIBLE_DOMAIN): defines the data-domain parameter, the is the domain for the Plausible analytics.
  • script (default to script.js): defines the Plausible script to use. See Script extensions for enhanced measurement for the list of alternative script names and what they can track for you.

Usage example:

{% load plausible %}
<html>
  <head>
      ...
      {% plausible domain='example.com' script='script.outbound-links.js' %}
  </head>

plausible_proxy.services.send_custom_event()

end a custom event to Plausible and return successful status.

See Plausible events API for more information

Arguments:

  • request (HttpRequest): Original Django HTTP request. Will be used to create X-Forwarded-For and User-Agent headers.
  • name (string): Name of the event. Can specify pageview which is a special type of event in Plausible. All other names will be treated as custom events.
  • domain (optional string): Domain name of the site in Plausible. The value from settings.PLAUSIBLE_DOMAIN is used by default.
  • url (optional string): URL of the page where the event was triggered. If not provided, the function extracts the URL from the request. If the URL contains UTM parameters, they will be extracted and stored. If URL is not set, will be extracted from the request.
  • referrer (optional string): Referrer for this event.
  • screen_width (optional integer): Width of the screen.
  • props (optional dict): Custom properties for the event. See: Using custom props.

Returns: True if request was accepted successfully.

Example:

def vote(request, candidate_id):
    candidate = get_object_or_404(Candidate, pk=candidate_id)
    send_custom_event(request, 'vote', props={"candidate": candidate.full_name})
    ...

Contributors

Project details


Download files

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

Source Distribution

django_plausible_proxy-0.4.0.tar.gz (9.5 kB view details)

Uploaded Source

Built Distribution

django_plausible_proxy-0.4.0-py3-none-any.whl (8.6 kB view details)

Uploaded Python 3

File details

Details for the file django_plausible_proxy-0.4.0.tar.gz.

File metadata

  • Download URL: django_plausible_proxy-0.4.0.tar.gz
  • Upload date:
  • Size: 9.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.4.0 CPython/3.10.8 Darwin/21.6.0

File hashes

Hashes for django_plausible_proxy-0.4.0.tar.gz
Algorithm Hash digest
SHA256 2f477ee830ccdb60ff586f2231251812fe9ca38a39212692ea1b52c1f0883663
MD5 3c36384f9a8445ba63abc1fb83e5189a
BLAKE2b-256 317071765f207ba3077298b4b3d05b8237146fbe20c5e5b9551bf7f448ffd47b

See more details on using hashes here.

Provenance

File details

Details for the file django_plausible_proxy-0.4.0-py3-none-any.whl.

File metadata

File hashes

Hashes for django_plausible_proxy-0.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c17582203e93f8dc27b69f18d86c3678cffd8c1a476470fd455ff64638426007
MD5 281c92faf68568fefb9ca92a281d4468
BLAKE2b-256 2ef0b281d81335049300586add06c80c2eb6e4d75a50f13449818d75b2489805

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page