How to add product analytics to a Django backend

uv add "amplitude-analytics>=1.2,<2"
# For a new project only:
uv add "django>=5.2,<5.3"
uv run django-admin startproject config .

[tool.uv]
exclude-newer = "7 days"

export AMPLITUDE_API_KEY="your-project-api-key"
export AMPLITUDE_SERVER_ZONE="US"

# Keep additions from later Python hub pages when merging this module.
from threading import Lock
import os
from amplitude import Amplitude, BaseEvent, EventOptions, Identify


def delivery_status(event, code, message=None):
    # Log the response code, never the payload, key, or user details.
    print(f"Amplitude delivery: HTTP {code}")


_client = None
_client_lock = Lock()


def get_client():
    global _client
    # Lock creation so simultaneous first requests share one client.
    with _client_lock:
        if _client is None:
            _client = Amplitude(os.environ["AMPLITUDE_API_KEY"])
            _client.configuration.callback = delivery_status
            _client.configuration.server_zone = os.environ.get("AMPLITUDE_SERVER_ZONE", "US")
        return _client


def shutdown_client():
    global _client
    with _client_lock:
        if _client is not None:
            try:
                for pending in _client.flush():
                    if pending is not None:
                        pending.result()
            finally:
                _client.shutdown()
                _client = None


def record_report_preview(user_id, device_id, framework, account_type=None):
    # Only device IDs come from the request. User IDs come from verified auth.
    if not isinstance(device_id, str) or not 5 <= len(device_id) <= 1024:
        device_id = None
    if user_id is None and device_id is None:
        return False
    client = get_client()
    if user_id is not None and account_type is not None:
        identify = Identify()
        identify.set("account_type", account_type)
        client.identify(identify, EventOptions(user_id=user_id, device_id=device_id))
    client.track(BaseEvent(
        event_type="Report Previewed",
        user_id=user_id,
        device_id=device_id,
        event_properties={"report_type": "usage", "days": 7, "framework": framework},
    ))
    return True

# Preserve this helper when adding later Django hub pages.
def get_current_user(request):
    user = request.user
    return user if user.is_authenticated else None

# Keep routes and decorators added by other Django hub pages.
from django.http import JsonResponse
from django.middleware.csrf import get_token
from django.views.decorators.http import require_http_methods
from .auth import get_current_user
from .analytics import record_report_preview


@require_http_methods(["GET", "POST"])
def report_preview(request):
    if request.method == "GET":
        return JsonResponse({"csrfToken": get_token(request)})
    user = get_current_user(request)
    # Use the same canonical ID format in browser instrumentation.
    user_id = f"user-{user.pk}" if user is not None else None
    # Replace these fixed preview values with your existing report computation.
    preview = {"report_type": "usage", "days": 7}
    record_report_preview(
        user_id=user_id,
        device_id=request.headers.get("X-Amplitude-Device-Id"),
        framework="django",
        account_type="staff" if user is not None and user.is_staff else
                     "member" if user is not None else None,
    )
    return JsonResponse(preview)

# Keep URL patterns added by other Django hub pages.
from django.urls import path
from .views import report_preview

urlpatterns = [path("reports/preview", report_preview)]

from django.urls import include, path

urlpatterns += [path("api/", include("metrics.urls"))]

uv run python manage.py migrate
uv run python manage.py runserver --noreload

from metrics.analytics import record_report_preview, shutdown_client

try:
    record_report_preview("user-42", None, "django", "member")
finally:
    shutdown_client()

uv run python -m scripts.send_report_event

curl -s -c /tmp/django-build-cookies http://127.0.0.1:8000/api/reports/preview > /tmp/django-build-csrf.json
CSRF_TOKEN=$(uv run python -c 'import json; print(json.load(open("/tmp/django-build-csrf.json"))["csrfToken"])')
curl -i -b /tmp/django-build-cookies -X POST \
  -H "X-CSRFToken: $CSRF_TOKEN" \
  -H "X-Amplitude-Device-Id: build-anonymous-device-42" \
  http://127.0.0.1:8000/api/reports/preview

# -- metrics/analytics.py --
# Keep additions from later Python hub pages when merging this module.
from threading import Lock
import os
from amplitude import Amplitude, BaseEvent, EventOptions, Identify


def delivery_status(event, code, message=None):
    # Log the response code, never the payload, key, or user details.
    print(f"Amplitude delivery: HTTP {code}")


_client = None
_client_lock = Lock()


def get_client():
    global _client
    # Lock creation so simultaneous first requests share one client.
    with _client_lock:
        if _client is None:
            _client = Amplitude(os.environ["AMPLITUDE_API_KEY"])
            _client.configuration.callback = delivery_status
            _client.configuration.server_zone = os.environ.get("AMPLITUDE_SERVER_ZONE", "US")
        return _client


def shutdown_client():
    global _client
    with _client_lock:
        if _client is not None:
            try:
                for pending in _client.flush():
                    if pending is not None:
                        pending.result()
            finally:
                _client.shutdown()
                _client = None


def record_report_preview(user_id, device_id, framework, account_type=None):
    # Only device IDs come from the request. User IDs come from verified auth.
    if not isinstance(device_id, str) or not 5 <= len(device_id) <= 1024:
        device_id = None
    if user_id is None and device_id is None:
        return False
    client = get_client()
    if user_id is not None and account_type is not None:
        identify = Identify()
        identify.set("account_type", account_type)
        client.identify(identify, EventOptions(user_id=user_id, device_id=device_id))
    client.track(BaseEvent(
        event_type="Report Previewed",
        user_id=user_id,
        device_id=device_id,
        event_properties={"report_type": "usage", "days": 7, "framework": framework},
    ))
    return True

# -- metrics/auth.py --
# Preserve this helper when adding later Django hub pages.
def get_current_user(request):
    user = request.user
    return user if user.is_authenticated else None

# -- metrics/views.py --
# Keep routes and decorators added by other Django hub pages.
from django.http import JsonResponse
from django.middleware.csrf import get_token
from django.views.decorators.http import require_http_methods
from .auth import get_current_user
from .analytics import record_report_preview


@require_http_methods(["GET", "POST"])
def report_preview(request):
    if request.method == "GET":
        return JsonResponse({"csrfToken": get_token(request)})
    user = get_current_user(request)
    # Use the same canonical ID format in browser instrumentation.
    user_id = f"user-{user.pk}" if user is not None else None
    # Replace these fixed preview values with your existing report computation.
    preview = {"report_type": "usage", "days": 7}
    record_report_preview(
        user_id=user_id,
        device_id=request.headers.get("X-Amplitude-Device-Id"),
        framework="django",
        account_type="staff" if user is not None and user.is_staff else
                     "member" if user is not None else None,
    )
    return JsonResponse(preview)

# -- metrics/urls.py --
# Keep URL patterns added by other Django hub pages.
from django.urls import path
from .views import report_preview

urlpatterns = [path("reports/preview", report_preview)]

from django.urls import include, path

urlpatterns += [path("api/", include("metrics.urls"))]

Add Amplitude product analytics to this existing Django app using /build/django-product-analytics.
Install amplitude-analytics with uv and preserve the project's uv.lock and release-age policy.
Merge new code into existing modules, routes, auth dependencies, and lifespan work. Never remove lines another Amplitude Build page added. Create the base auth helper and report preview route if absent.
Reuse one SDK client per worker, initialized after fork. Keep user_id and device_id on each event and EventOptions, never on shared mutable request identity. Get user IDs only from verified auth. Preserve the existing canonical ID convention and ensure IDs have at least five characters.
Forward the existing browser device ID for anonymous requests. Skip analytics if neither ID is usable. Never treat a device header as authentication, and never create a shared anonymous user ID.
Track Report Previewed after computing the report, with report_type=usage, days=7, and framework=django. Set account_type using Identify before the event for signed-in users.
Preserve authorization and CSRF controls. Keep API keys in process environment and log delivery status without payloads or credentials.
Preserve Django middleware and root URL patterns; do not initialize in AppConfig.ready or a pre-fork master.
Flush and close the SDK at graceful worker/job exit; do not shut it down after each request.
Report files changed and verify anonymous identity, signed-in identity, concurrent users, invalid device IDs, and exit delivery. Confirm remote ingestion separately in Amplitude.