Getting Started

Minimal Setup

Install the package:
```
composer require kerkness/fa-wired
```

Include the JS in your main JS file (Vite recommended):

import 'vendor/kerkness/fa-wired/dist/fa-wired.esm.js';

Verify Fathom script is loaded in your <head> (e.g., via Fathom's official script tag).

First Use Case: Track a Button Click

Add the x-fathom-track directive to any HTML element:

<button x-fathom-track="'Button Clicked'">Click Me</button>

No additional configuration needed.

Implementation Patterns

Alpine.js Directives (Blade Templates)

Directive	Usage Example	Notes
`x-fathom-track`	`<a x-fathom-track="'Link Click'">`	Tracks clicks (links, buttons, etc.).
`x-fathom-form-submit`	`<form x-fathom-form-submit>`	Tracks form submissions.
`x-fathom-download`	`<a x-fathom-download="'PDF'">`	Tracks file downloads.
`x-fathom-external`	`<a x-fathom-external href="...">`	Tracks external links (auto-detects).

Dynamic Events:

<button x-fathom-track="`Product View: ${product.id}`">View</button>

Livewire Integration

Dispatch Events:

// In Livewire component
public function save() {
    $this->dispatch('fathom-track', event: 'Form Saved');
}

Listen in JS (auto-registered via fa-wired):

// No manual setup needed; events bubble up automatically.

Programmatic Tracking (JavaScript)

Use the $fathom global helper:

// Track a custom event
$fathom.track('Custom Event', { property: 'value' });

// Track e-commerce (values in cents)
$fathom.track('Purchase', { revenue: 2999 }); // $29.99

E-Commerce Tracking

<!-- Blade -->
<button x-fathom-track="'Purchase'" data-fathom-value="2999">
    Buy Now ($29.99)
</button>

Values are automatically converted to dollars.

Configuration

Publish the config (optional):

php artisan vendor:publish --provider="Kerkness\FaWired\FaWiredServiceProvider" --tag="config"

Modify config/fa-wired.php to:

Set default event properties.
Exclude specific routes/paths.

Gotchas and Tips

Pitfalls

Fathom Script Missing:
- If events don’t fire, verify Fathom’s script is loaded before fa-wired.
- Debug with browser console: $fathom should be defined.

Livewire Event Timing:

Dispatch fathom-track after the action completes (e.g., in saved() hook).

Example:

protected $listeners = ['fathom-track' => 'handleFathomEvent'];
public function handleFathomEvent($event) { /* ... */ }

Alpine.js Conflicts:
- Ensure fa-wired is loaded after Alpine.js in your build process.
- If using multiple Alpine plugins, test directives in isolation.

Debugging

Check Console Logs:
- fa-wired logs events to console.log (enable in config/fa-wired.php):
```
'debug' => env('FA_WIRED_DEBUG', false),
```
Verify Event Payloads:
- Inspect network requests to https://analytics.example.com (replace with your Fathom URL).
Test in Incognito:
- Avoid cached Alpine directives during development.

Extension Points

Custom Directives: Extend the package by adding new Alpine directives:

// In your JS file
document.addEventListener('alpine:init', () => {
    Alpine.directive('custom-track', (el, { expression }) => {
        $fathom.track(expression);
    });
});

Usage:

<div x-custom-track="'Custom Event'"></div>

Override Default Behavior: Re-publish the config and modify:

'event_prefix' => 'app.', // Prefix all events with "app."
'exclude_paths' => ['/admin/*'], // Ignore admin routes

Server-Side Fallback: For critical events (e.g., purchases), combine with server-side tracking:

// In your controller
event(new \Kerkness\FaWired\Events\FathomTrack('Purchase', ['revenue' => 2999]));

Performance Tips

Debounce Rapid Events: Disable tracking for rapid-fire actions (e.g., autocomplete suggestions):

<input x-data="{ throttled: false }"
       @click.debounce="throttled = true"
       x-fathom-track="'Search'" x-bind:disabled="throttled">

Lazy-Load Directives: Defer initialization for off-screen elements:

<div x-data="{ init: false }" @visible.window="init = true" x-bind:init="init">
    <button x-fathom-track="'Lazy Track'">Click</button>
</div>

Batch Events: For high-traffic pages, batch events using Fathom’s API:
```
$fathom.batch([{ name: 'Event 1' }, { name: 'Event 2' }]);
```

Fa Wired Laravel Package