GhostScript Documentation
Complete guide to implementing privacy-first analytics with GhostScript.
📦 Installation
Getting started with GhostScript is simple. Add our lightweight tracking script to your website and start collecting insights immediately.
Step 1: Add the Script
Add this script tag to your website's <head>
section or just before the closing </body>
tag:
<script defer src="https://ghostscript.xyz/ghost.js?key=YOUR_PUBLIC_KEY"></script>
💡 Pro tip: Replace YOUR_PUBLIC_KEY
with your actual public key from your dashboard.
Step 2: Verify Installation
Once installed, you should see data flowing into your dashboard within minutes. The script:
- ✅ Loads asynchronously (won't block your page)
- ✅ Is under 2KB gzipped
- ✅ Works without cookies
- ✅ Respects Do Not Track headers
⚙️ Configuration
GhostScript works out of the box, but you can customize its behavior with these options:
<script>
window.ghostscript = window.ghostscript || {
domain: 'example.com', // Track specific domain only
trackOutbound: true, // Track outbound link clicks
trackDownloads: true, // Track file downloads
trackHash: false, // Track hash changes as pageviews
respectDNT: true // Respect Do Not Track
};
</script>
<script defer src="https://ghostscript.xyz/ghost.js?key=YOUR_PUBLIC_KEY"></script>
📊 Basic Tracking
GhostScript automatically tracks pageviews when the script loads. No additional configuration needed!
What's Tracked Automatically
- Pageviews: Every page load and navigation
- Referrers: Where visitors came from
- UTM Parameters: Campaign tracking data
- Device Type: Desktop, mobile, or tablet
- Country: Visitor's country (from IP)
🎯 Custom Events
Track specific user actions with custom events. Perfect for measuring conversions, engagement, and user behavior.
Basic Event Tracking
// Track a simple event
ghostscript.track('signup');
// Track an event with properties
ghostscript.track('purchase', {
plan: 'pro',
amount: 19,
currency: 'USD'
});
// Track with additional context
ghostscript.track('video_play', {
video_title: 'Product Demo',
duration: 120,
source: 'landing_page'
});
Common Event Examples
E-commerce
ghostscript.track('add_to_cart', {
product_id: 'shirt-123',
value: 29.99
});
SaaS
ghostscript.track('feature_used', {
feature: 'export_data',
plan: 'pro'
});
🎯 Goals & Funnels
Set up conversion goals and track user journeys through your funnel.
Setting Up Goals
Goals can be based on:
- Page visits: When users reach a specific page
- Custom events: When specific actions are performed
- Event properties: When events have specific values
🎯 Example Goal: Track signups by creating a goal for the 'signup' event or visits to '/welcome' page.
🔗 UTM Tracking
Track campaign performance with UTM parameters. GhostScript automatically captures and reports on all UTM data.
Supported UTM Parameters
utm_source
The source of your traffic (e.g., google, facebook, newsletter)
utm_medium
The medium (e.g., cpc, email, social)
utm_campaign
The campaign name (e.g., summer_sale, product_launch)
utm_content
Specific ad or link content
Example Campaign URL
https://yoursite.com?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale
⚡ Real-time Data
GhostScript provides real-time analytics through WebSocket connections, giving you instant insights into your website activity.
What Updates in Real-time
- Current active visitors
- Pageviews as they happen
- Custom events
- Geographic data
- Traffic sources
📈 Metrics Reference
Understanding what each metric means and how it's calculated.
Pageviews
Definition: Total number of pages viewed. Repeated views of a single page are counted.
Use case: Measure total site activity and content popularity.
Sessions
Definition: A group of interactions by a user within a 30-minute window.
Use case: Understand user engagement and visit patterns.
Conversions
Definition: Completed goals or desired actions.
Use case: Measure business objectives and ROI.
Referrers
Definition: Sources that sent traffic to your site.
Categories: Direct, Search engines, Social media, Referral sites
🔌 API Documentation
Access your analytics data programmatically with our REST API.
Authentication
API requests require authentication using your API token:
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://ghostscript.xyz/api/stats
Available Endpoints
GET /api/stats
Get general statistics for a date range
GET /api/stats?start=2024-01-01&end=2024-01-31&website_id=123
GET /api/events
Get custom events data
GET /api/events?event_name=signup&start=2024-01-01
GET /api/pages
Get top pages and their performance
GET /api/pages?limit=10&website_id=123
Data Export
Export your data in CSV format for further analysis:
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://ghostscript.xyz/api/export?format=csv&start=2024-01-01 \
-o analytics_data.csv
🔒 Privacy & Compliance
GhostScript is designed with privacy at its core. Here's what we do to protect user privacy:
🍪 No Cookies
We don't use cookies or local storage to track users.
🔒 No Personal Data
No emails, names, or other personally identifiable information.
🌍 GDPR Compliant
Fully compliant with GDPR and other privacy regulations.
🚫 Respects DNT
Honors Do Not Track browser settings.
💬 Need Help?
We're here to help you succeed with GhostScript analytics.
📧 Email Support
Send us an email at help@ghostscript.com
💬 Community
Join our community forum for tips and discussions