README

A Laravel package that provides Alpine.js directives and magic helpers for seamless Fathom Analytics event tracking in Blade templates and Livewire components.

Features

🎯 Alpine.js Directives - Simple HTML attributes for tracking clicks, form submissions, downloads, and external links
✨ Magic Helper - $fathom magic helper for programmatic tracking in JS
🔥 Livewire Integration - dispatch tracking events from Livewire components
📊 Track E-commerce Values - Track conversions with values in cents

Requirements

Laravel 10+
PHP 8.2+
Alpine.js 3.x
Livewire 3.x
Fathom Analytics account with script included in your site

Installation

1. Install via Composer

composer require kerkness/fa-wired

2. Include the JavaScript

Option A: Import in your build process (Recommended)

If you're using Vite, or another build tool:

// In your app.js or main JavaScript file
import 'vendor/kerkness/fa-wired/dist/fa-wired.esm.js';

// Or with explicit import
import FaWired from 'vendor/kerkness/fa-wired/dist/fa-wired.esm.js';

Option B: Include directly in Blade template

<!-- Your existing scripts -->
<script src="https://cdn.usefathom.com/script.js" data-site="YOUR-SITE-ID" defer></script>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

<!-- fa-wired from vendor directory -->
<script src="{{ asset('vendor/kerkness/fa-wired/dist/fa-wired.js') }}"></script>

Option C: Via CDN (Alternative)

<script src="https://cdn.jsdelivr.net/gh/kerkness/fa-wired@latest/dist/fa-wired.js"></script>

3. Publish Assets (Optional)

If you want to customize or host the JavaScript yourself:

php artisan vendor:publish --provider="Kerkness\FaWired\FaWiredServiceProvider" --tag="fa-wired-assets"

This will copy the compiled JavaScript files to public/vendor/fa-wired/.

Quick Start

Track Button Clicks

<button x-track-click="header cta">Get Started</button>

Track Form Submissions

<form x-track-submit="newsletter signup">
    <input type="email" placeholder="Enter email">
    <button type="submit">Subscribe</button>
</form>

Track from Livewire Components

// In your Livewire component
public function submit()
{
    // Process form...
    
    $this->dispatch('fathom-track', name: 'contact form submitted');
}

Usage Guide

Alpine.js Directives

Simple Click Tracking

<button x-track-click="button click">
    Track Simple Click
</button>

Click Tracking with Value

<button x-track-click="{ event: 'premium button', value: 2500 }">
    Track Click with Value ($25.00)
</button>

Form Submission Tracking

<form x-track-submit="newsletter signup">
    <input type="email" placeholder="Enter email">
    <button type="submit">Subscribe</button>
</form>

Download Tracking

<!-- Auto-named download event -->
<a href="/files/guide.pdf" x-track-download>
    Download User Guide
</a>

<!-- Custom event name -->
<a href="/files/pricing.pdf" x-track-download="pricing guide download">
    Download Pricing
</a>

External Link Tracking

<a href="https://example.com" x-track-external="partner site visit">
    Visit Partner Site
</a>

Magic Helper ($fathom)

Simple Event Tracking

<button @click="$fathom.track('magic helper test')">
    Simple Track
</button>

Conversion Tracking

<div x-data="{ productPrice: 4999 }">
    <button @click="$fathom.conversion('product purchase', productPrice)">
        Track Conversion ($49.99)
    </button>
</div>

Advanced Usage

<div x-data="{ 
    trackingData: { clicks: 0 },
    trackComplexEvent() {
        this.trackingData.clicks++;
        $fathom.track('complex interaction', this.trackingData.clicks * 100);
    }
}">
    <button @click="trackComplexEvent()">
        Complex Tracking
    </button>
</div>

Livewire Integration

In your Livewire Component (PHP)

<?php

namespace App\Livewire;

use Livewire\Component;

class ContactForm extends Component
{
    public function submit()
    {
        // Process form...
        
        // Track simple event
        $this->dispatch('fathom-track', name: 'contact form submitted');
        
        // Track with value (e.g., for lead scoring)
        $this->dispatch('fathom-track', 
            name: 'high value lead', 
            value: 5000 // $50.00 in cents
        );
    }
    
    public function purchaseSubscription($planPrice)
    {
        // Process purchase...
        
        // Track conversion
        $this->dispatch('fathom-conversion', 
            name: 'subscription purchased', 
            value: $planPrice * 100 // Convert to cents
        );
    }
    
    public function registerUser()
    {
        // Process registration...
        
        // Track form submission
        $this->dispatch('fathom-form-submit', name: 'user registration');
    }
}

Laravel Blade Examples

Dynamic Event Names

<button x-track-click="product view: {{ $product->name }}">
    View {{ $product->name }}
</button>

Conditional Tracking

@if($user->isPremium())
    <button x-track-click="{ event: 'premium feature used', value: 1000 }">
        Premium Feature
    </button>
@else
    <button x-track-click="upgrade prompt shown">
        Upgrade to Premium
    </button>
@endif

E-commerce Example

<div x-data="{ 
    cart: { total: 0, items: [] },
    addToCart(product, price) {
        this.cart.items.push(product);
        this.cart.total += price;
        $fathom.track('add to cart: ' + product, price);
    },
    checkout() {
        $fathom.conversion('checkout completed', this.cart.total);
    }
}">
    <p>Cart Total: $<span x-text="(cart.total / 100).toFixed(2)"></span></p>
    
    <button @click="addToCart('Widget A', 1999)">
        Add Widget A ($19.99)
    </button>
    
    <button @click="addToCart('Widget B', 2999)">
        Add Widget B ($29.99)
    </button>
    
    <button @click="checkout()" x-show="cart.total > 0">
        Checkout
    </button>
</div>

API Reference

Available Methods

Alpine Store Methods

Alpine.store('fathom').track(eventName, value)
Alpine.store('fathom').click(eventName, value)
Alpine.store('fathom').submit(eventName, value)
Alpine.store('fathom').conversion(eventName, value)
Alpine.store('fathom').download(fileName, eventName)
Alpine.store('fathom').externalLink(url, eventName)

Magic Helper Methods

$fathom.track(eventName, value)
$fathom.click(eventName, value)
$fathom.submit(eventName, value)
$fathom.conversion(eventName, value)
$fathom.download(fileName, eventName)
$fathom.externalLink(url, eventName)

Livewire Events

$this->dispatch('fathom-track', name: 'event name', value: 1000);
$this->dispatch('fathom-form-submit', name: 'event name', value: 1000);
$this->dispatch('fathom-conversion', name: 'event name', value: 1000);

Configuration

Auto-tracking Features

By default, auto-tracking is disabled. You can enable it like this:

// Enable auto-tracking for external links and downloads
FaWired.configure({
    autoTrackExternalLinks: true,
    autoTrackDownloads: true
});

Best Practices

Event Naming

Use descriptive, consistent names
Avoid special characters and emojis
Use lowercase with spaces or underscores
Examples: newsletter signup, product_purchase, file download

Value Tracking

Always provide values in cents (100 = $1.00)
Use consistent currency across your site
Set currency in Fathom dashboard settings

Common Event Types

// User interactions
$fathom.track('button click: header cta');
$fathom.track('menu opened');
$fathom.track('search performed');

// Form submissions
$fathom.submit('contact form');
$fathom.submit('newsletter signup');
$fathom.submit('user registration');

// E-commerce
$fathom.conversion('product purchased', 2999);
$fathom.track('add to cart', 1999);
$fathom.track('checkout started');

// Content engagement
$fathom.track('video play');
$fathom.download('user-guide.pdf');
$fathom.externalLink('https://partner.com');

Troubleshooting

Common Issues

Events not tracking: Ensure Fathom script loads before fa-wired
Console warnings: Check that fathom object exists globally
Livewire events not firing: Verify event names match exactly

Debug Mode

Enable debug mode to see all tracking calls:

// Add this after fa-wired loads
Alpine.store('fathom').track = function(eventName, value = null) {
    console.log('Tracking:', eventName, value); // Debug line
    if (typeof fathom === 'undefined') {
        console.warn('Fathom Analytics not loaded');
        return;
    }
    const options = value ? { _value: value } : {};
    fathom.trackEvent(eventName, options);
};

Script Load Order

Make sure scripts load in this order:

Fathom Analytics script
Alpine.js
fa-wired
Your custom scripts

License

The MIT License (MIT). Please see License File for more information.

kerkness / fa-wired

Maintainers

Details