GhostScript GhostScript Documentation

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