Skip to content
Botscent

Django

Add the server half of Botscent to a Django project and check the install.

Add the server half of Botscent to a Django project. The server half runs as Django middleware and puts the request's own verdict on request.botscent. For the page half, see A script tag, React, Vue or the page for the framework your site uses.

Before you start

You need:

  • A Django project
  • Python 3.11 or later

1. Install the package

Install botscent from PyPI.

Terminal
pip install botscent

With uv or poetry, use uv add botscent or poetry add botscent.

2. Add the server half

In example/settings.py, add botscent.django.BotscentMiddleware to MIDDLEWARE. Keep your existing entries.

example/settings.py
MIDDLEWARE = [
    # your existing middleware
    "botscent.django.BotscentMiddleware",
]

Every request now carries its own verdict on request.botscent.

The middleware works in sync and async middleware stacks.

By default, the middleware does not send the verdict to the page. Django runs at the origin, and an origin cannot see whether a CDN in front of it stores HTML. The BOTSCENT_TRANSPORT = True setting turns the sending on. For the details, see From the server to the page.

Warning: Do not set BOTSCENT_TRANSPORT = True unless no shared cache stores your HTML. If a cache stores an agent's page and ignores Cache-Control: no-store, a person can get the agent's Server-Timing entry. If you are not sure, keep the default.

3. Add the page half

The server half reads only what each request declares. The page half finds agents that operate a browser, from inside the page. The page half comes from the npm package botscent.

If Django renders your HTML, add <script defer src="/botscent.js"></script> to each template. Serve node_modules/botscent/dist/botscent.js at /botscent.js from your own origin. If a frontend framework renders your pages, add the page half there instead. The Quickstart lists every framework.

4. Read the verdict

In a view, read request.botscent.

example/urls.py
from django.http import JsonResponse
from django.urls import path


def verdict(request):
    return JsonResponse(request.botscent)


urlpatterns = [path("verdict", verdict)]

A request from curl to /verdict gets {"type": "agent", "agent_name": "curl", "reasons": ["ua.declared-agent-token"]}.

To give an agent access, use botscent.is_verified(request.botscent). Use no other field for access. See The trust model.

5. Check the install

Start the app. Then run the check against one of its pages.

Terminal
npx botscent check http://localhost:8000/

The page-script check prints pass, and the check exits with code 0. The server-half check prints unknown, because the transport is off at an origin. If a check fails, see Verify your install.

Next steps