Complete Documentation

Fikrah Analytics Documentation

Everything you need to set up, customize, and extend your privacy-first analytics platform

Quick Start Guide

Get your analytics platform running in 5 minutes

Install Dependencies

npm install

Setup Database

Run schema.sql in Supabase

Configure & Launch

npm run dev

Configuration

Environment variables and project setup

Environment Variables

NEXT_PUBLIC_SUPABASE_URL=your_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_key
SUPABASE_SERVICE_ROLE_KEY=your_service_key

Getting Supabase Keys

Create project at supabase.com
Go to Settings → API
Copy your URL and keys
Add to .env.local file

Database Schema

Understanding the analytics data structure

Core Tables

sitesYour domains

visitorsUnique users

sessionsUser sessions

page_viewsPage visits

eventsCustom events

Run the complete schema from database/schema.sql

Customization Guide

Make Fikrah Analytics your own

Branding & UI

Logo & Name

Edit app/layout.js and components to replace "Fikrah Analytics"

Colors

Modify globals.css CSS variables for your brand colors

Landing Page

Customize app/page.js for your product positioning

Feature Extensions

Custom Events

Add event tracking in tracker.js and dashboard queries

New Charts

Use Recharts library to add funnel, retention charts

Exports

Add CSV/PDF export functionality to dashboard

Privacy Features

No Cookies: Uses localStorage for visitor IDs

Anonymized: No personal data stored

GDPR Ready: Compliant by design

Self-hosted: Full data ownership

Real-time Features

Live Visitors: See current active users

Heartbeat: 15-second activity tracking

Auto Cleanup: Removes stale visitors

Live Updates: Dashboard refreshes automatically

Developer Tools

API Ready: RESTful analytics endpoints

Direct SQL: Custom queries in Supabase

Configurable: Easy environment setup

Fast Deploy: Vercel/Netlify ready

How Tracking Works (Technical)

Understanding the analytics implementation for customization

Tracking Script (public/tracker.js)

The tracking script automatically captures visitor data and sends it to your API:

// Auto-tracks on page load
analytics.track('page_view', {page: '/home'});

// Manual event tracking  
analytics.track('button_click', {button: 'signup'});

// Custom conversion tracking
analytics.track('conversion', {value: 29, product: 'analytics'});

Adding Custom Events

1. Client-Side Tracking

// In your React components
const handleDownload = () => {
  // Your download logic
  analytics.track('file_download', {
    file: 'source-code.zip',
    price: 29
  });
};

2. Server-Side Processing

// In app/api/analytics/collect/route.js
case 'file_download':
  await handleCustomEvent(data);
  break;

// Add your custom logic here

Custom Dashboard Queries

Adding New Chart Data

// In app/dashboard/page.jsx
const fetchConversionData = async () => {
  const { data } = await supabase
    .from('events')
    .select('*')
    .eq('event_type', 'conversion')
    .gte('created_at', startDate);
  return data;
};

Real-time Data Updates

// Auto-refresh every 30 seconds
useEffect(() => {
  const interval = setInterval(fetchData, 30000);
  return () => clearInterval(interval);
}, []);

Available API Endpoints

POST /api/analytics/collect

Send tracking events

GET /api/test-connection

Test database connection

Example API Call:

fetch('/api/analytics/collect', {
  method: 'POST',
  body: JSON.stringify({event: 'signup'})
})

Tracker Configuration

Modify tracking behavior in public/tracker.js:

const config = {
  endpoint: '/api/analytics/collect',
  debug: false, // Set to true for console logs
  trackScrollDepth: true, // Track how far users scroll
  trackTimeOnPage: true, // Track session duration
  heartbeatInterval: 15000, // Ping every 15 seconds
  trackUTM: true, // Capture UTM parameters
  respectDoNotTrack: true // Honor DNT header
};

Deployment Guide

Deploy your analytics platform to production