F

FairCite Documentation

Integration Guide for Publishers

Dashboard

Troubleshooting Guide

Common issues and solutions for FairCite integration across all platforms.

Quick Diagnostics

Before diving into specific issues, verify these basic requirements:

  • Valid Credentials: Site ID and API Key are correct
  • Network Connectivity: Can reach edge.faircite.com
  • Platform Compatibility: Using supported versions
  • Integration Active: Middleware/plugin is enabled

Credential & Authentication Issues

"Invalid Site ID or API Key" Error

Common Causes:

  • Extra spaces in copied credentials
  • Site ID and API Key swapped in wrong fields
  • Using test credentials in production
  • Credentials regenerated but not updated

Solutions:

  1. Verify credentials format:
    Site ID: pub_XXXXXXXXXXXX API Key: sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  2. Copy credentials fresh from your dashboard
  3. Check for invisible characters - retype instead of copy-paste
  4. Verify domain match between dashboard and actual site
  5. Regenerate credentials in FairCite dashboard if needed

Connection Test Fails

Network Diagnostics:

  1. Test connectivity:
    curl -I https://edge.faircite.com/health
  2. Check DNS resolution:
    nslookup edge.faircite.com
  3. Verify HTTPS support - FairCite requires SSL

Server Requirements:

  • Outbound HTTPS requests allowed
  • No firewall blocking edge.faircite.com
  • PHP curl extension enabled (WordPress)
  • Node.js fetch/axios available (JavaScript platforms)

Data Collection Issues

No Data Appearing in Dashboard

Debugging Steps:

  1. Wait for processing: Initial data may take 1-2 minutes
  2. Generate test traffic: Visit your site from different browsers
  3. Check integration status: Verify middleware/plugin is active
  4. Enable debug mode: Look for console errors or logs
  5. Inspect network requests: Check browser dev tools

Platform-Specific Checks:

WordPress:
  • Ensure "Enable Bot Detection" is checked
  • Clear WordPress cache if using caching plugins
  • Check for pending batches, click "Flush Batches Now"
  • Verify JavaScript is loading without errors
Next.js:
  • Verify middleware.ts is in project root
  • Check matcher patterns include your routes
  • Enable FC_DEBUG=true to see logs
  • Restart development server after changes
Express/Node.js:
  • Confirm middleware is registered correctly
  • Check middleware order (should be early in stack)
  • Verify environment variables are loaded
  • Test with debug: true configuration

Partial or Inconsistent Data

Common Causes:

  • Caching conflicts: CDN or server caching blocking requests
  • Ad blockers: User extensions blocking tracking
  • Network issues: Intermittent connectivity problems
  • Rate limiting: Server or hosting provider limitations

Solutions:

  1. Whitelist edge.faircite.com in CDN settings
  2. Test from multiple networks and browsers
  3. Check batch settings - increase flush interval if needed
  4. Monitor error logs for failed requests

Platform-Specific Issues

WordPress Issues

Plugin conflicts:
  • Deactivate other tracking plugins temporarily
  • Check for JavaScript errors in console
  • Test with default theme
Performance plugins:
  • Whitelist FairCite JavaScript from minification
  • Exclude from lazy loading
  • Clear all caches after installation
Security plugins:
  • Whitelist edge.faircite.com domain
  • Allow outbound HTTPS connections
  • Check firewall logs for blocked requests

Next.js Issues

Middleware not running:
  • Ensure Next.js version is 12.2+
  • Place middleware.ts in project root
  • Check config.matcher patterns
Edge Runtime issues:
  • Avoid Node.js specific APIs
  • Use Web APIs only in middleware
  • Test locally before deploying
Deployment problems:
  • Set environment variables in deployment
  • Redeploy after configuration changes
  • Check function logs for errors

Performance Issues

Site Slowdown

FairCite is designed for minimal performance impact, but configuration issues can cause problems.

Optimization Tips:

  • Increase batch size: Reduce API call frequency
  • Adjust flush interval: Less frequent but larger batches
  • Enable async processing: Non-blocking requests
  • Use CDN whitelisting: Bypass caching for tracking

Recommended Settings:

{
  batchSize: 20,        // Higher for busy sites
  flushInterval: 5000,  // 5 seconds for less frequent calls
  enabled: true,        // Can disable for debugging
  debug: false          // Only enable for troubleshooting
}

Getting Additional Help

Before Contacting Support

  • Test connection with curl/browser tools
  • Enable debug mode and collect logs
  • Try from different browsers/networks
  • Check hosting provider documentation
  • Review FAQ section

Support Channels

Email Support:
support@faircite.com
Response within 24 hours
Include in Your Request:
  • Platform/framework version
  • Error messages or logs
  • Site URL (if publicly accessible)
  • Steps already attempted
Dashboard Access:
dashboard.faircite.com
Check real-time status and logs