F

FairCite Documentation

Integration Guide for Publishers

Dashboard

Django Middleware Integration

Python middleware for Django applications with intelligent bot detection and async processing.

Time Required: 10 minutesDifficulty: EasyDjango Version: 3.0+

Prerequisites

  • Python 3.7+ and Django 3.0+
  • FairCite account with Site ID and API key
  • requests library (usually included)
Don't have credentials yet? Create your FairCite account first

Installation

Install the FairCite Django middleware package:

pip install faircite-django

Or add to your requirements.txt:

requirements.txt
faircite-django>=1.0.0

Configuration

1. Add to Django Settings

Add FairCite middleware to your Django settings:

settings.py
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    
    # Add FairCite middleware here
    'faircite.middleware.FairCiteMiddleware',
    
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

# FairCite Configuration
FAIRCITE_SITE_ID = 'pub_xxxxx'
FAIRCITE_API_KEY = 'fc_xxxxx'
FAIRCITE_DEBUG = DEBUG  # Use Django's debug setting

2. Environment Variables (Recommended)

For better security, use environment variables:

.env
FAIRCITE_SITE_ID=pub_xxxxx
FAIRCITE_API_KEY=fc_xxxxx
FAIRCITE_DEBUG=False
settings.py
import os
from dotenv import load_dotenv

load_dotenv()

# FairCite Configuration
FAIRCITE_SITE_ID = os.getenv('FAIRCITE_SITE_ID')
FAIRCITE_API_KEY = os.getenv('FAIRCITE_API_KEY')
FAIRCITE_DEBUG = os.getenv('FAIRCITE_DEBUG', 'False').lower() == 'true'

3. Advanced Settings

settings.py
# Optional FairCite settings
FAIRCITE_CONFIG = {
    'SITE_ID': os.getenv('FAIRCITE_SITE_ID'),
    'API_KEY': os.getenv('FAIRCITE_API_KEY'),
    'EDGE_URL': 'https://edge.faircite.com/v1/analyze',
    'ENABLED': True,
    'BATCH_SIZE': 10,
    'FLUSH_INTERVAL': 1000,  # milliseconds
    'TIMEOUT': 5,  # seconds
    'DEBUG': DEBUG,
    
    # Paths to exclude from tracking
    'EXCLUDE_PATHS': [
        '/admin/',
        '/api/health/',
        '/static/',
        '/media/',
    ],
    
    # User agents to exclude
    'EXCLUDE_USER_AGENTS': [
        'HealthCheck',
        'Monitor',
    ]
}

Usage Examples

Basic Django Project

views.py
from django.shortcuts import render
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt

def home(request):
    """Home page view - automatically tracked by FairCite middleware"""
    return render(request, 'home.html')

def api_users(request):
    """API endpoint - also tracked automatically"""
    users = [{'id': 1, 'name': 'John'}, {'id': 2, 'name': 'Jane'}]
    return JsonResponse({'users': users})

@csrf_exempt
def webhook(request):
    """Webhook endpoint - tracked to identify bot scrapers"""
    if request.method == 'POST':
        # Process webhook data
        return JsonResponse({'status': 'received'})
    return JsonResponse({'error': 'Method not allowed'}, status=405)

Django REST Framework

views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status

class UserListView(APIView):
    """DRF view - FairCite middleware works with all Django views"""
    
    def get(self, request):
        # This endpoint will be tracked for bot activity
        users = User.objects.all()
        serializer = UserSerializer(users, many=True)
        return Response(serializer.data)
    
    def post(self, request):
        # POST requests also tracked
        serializer = UserSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

Testing & Verification

Enable Debug Logging

Add logging configuration to see FairCite activity:

settings.py
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'faircite': {
            'handlers': ['console'],
            'level': 'DEBUG' if DEBUG else 'INFO',
            'propagate': False,
        },
    },
}

Test the Integration

  1. Start your Django development server:
    python manage.py runserver
  2. Visit several pages on your site
  3. Check console output for FairCite debug messages
  4. Log into your FairCite dashboard
  5. Verify data appears in Analytics section within 1-2 minutes

Troubleshooting

Middleware Not Loading

  • Check that 'faircite.middleware.FairCiteMiddleware' is in MIDDLEWARE list
  • Verify package installation: pip show faircite-django
  • Ensure middleware is placed after authentication middleware
  • Restart Django server after configuration changes

Authentication Errors

  • Verify FAIRCITE_SITE_ID and FAIRCITE_API_KEY are correct
  • Check environment variables are loaded properly
  • Test credentials with curl or requests library manually
  • Enable debug logging to see detailed error messages

Performance Optimization

  • Increase BATCH_SIZE for high-traffic applications
  • Add frequently accessed paths to EXCLUDE_PATHS
  • Consider using async views for better performance
  • Monitor Django logs for any performance warnings

Next Steps