Footprints

Footprints is a free, MIT-licensed Laravel 7+ package from developer Kyranb that captures UTM parameters and HTTP referrers from unauthenticated requests and links them to user registrations, giving you a self-hosted registration attribution tracking solution. It installs via Composer, publishes a migration and config file, and adds a middleware to your Laravel app.

What is Footprints?

Footprints is a Laravel 7+ registration attribution tracking package that takes incoming HTTP request data (UTM parameters, referrer URL and domain, landing page, and optionally IP address) and stores it as Visit records. When a trackable model such as the User model is created, the package links previous visits to that model so you can see exactly which marketing channel led to the signup. It provides a configurable middleware, an Eloquent Visit model, and an Artisan pruning command.

Key Features

• Middleware-based tracking — Add CaptureAttributionDataMiddleware globally or to selected route groups; only requests passing through the middleware are recorded.
• Configurable attribution duration — Set attribution_duration in seconds (default 2628000, about one month) to control how long visits remain eligible to be assigned to a new registration.
• Trackable model trait — Implement TrackableInterface and use the TrackRegistrationAttribution trait on any Eloquent model to get visits, initialAttributionData(), and finalAttributionData() methods.
• Visit data fields — Stores landing page, referrer URL, referrer domain, all five UTM parameters (source, medium, campaign, term, content), and created date, with optional IP tracking.
• Cookie or IP fallback linking — Uses a footprints cookie by default; set uniqueness => false to link visits by IP address and User-Agent header when cookies are disabled.
• Swappable components — Replace the default TrackingLogger, TrackingFilter, or Footprinter with any class implementing the corresponding interface for custom behavior.
• Robots exclusion — Install jaybizzle/crawler-detect and set disable_robots_tracking => true to skip tracking crawlers from Google, Bing, and other bots.
• Pruning command — Schedule footprints:prune to run daily; it deletes unassigned visits older than the configured duration, and accepts a --days option (for example --days=10).

Who is it for?

• Laravel developers building SaaS or ecommerce applications who want to add attribution tracking without integrating a third-party analytics SDK.
• Marketing teams collaborating with developers to measure ROI on paid ads, email campaigns, and referral links by reviewing the UTM data captured per signup.
• Startups seeking a lightweight, open-source way to understand which channels drive user registration and focus their advertising spend.

What can you do with Footprints?

• Paid acquisition managers: attribute each new user to the exact utm_campaign, utm_content, and utm_term that brought them, then compare campaign performance directly in your database.
• Email marketers: tag links with UTM parameters and see which email campaigns, subject lines, or CTAs generate the most registrations.
• Product analysts: retrieve a user's full visit history before signup, plus their initial and final attribution data, to analyze multi-touch acquisition paths.

How does Footprints work?

When a request passes through the CaptureAttributionDataMiddleware, the TrackingFilter decides if it should be logged. If yes, TrackingLogger saves a Visit record with a footprint identifier calculated by the Footprinter — a cookie value, or IP/User-Agent when cookies are disabled. When a trackable model is created, the AssignPreviousVisits job looks up Visit records with a matching footprint and links them to that new user.

FAQ

How do I install Footprints?

Run composer require kyranb/footprints, then publish the config and migration files with php artisan vendor:publish --provider="Kyranb\Footprints\FootprintsServiceProvider". Add CaptureAttributionDataMiddleware to your kernel after EncryptCookies, and implement TrackableInterface with the TrackRegistrationAttribution trait on the model you want to track.

Does Footprints work with Laravel 6?

No, Footprints requires Laravel 7 or higher, as stated in the package requirements.

Can I track a model other than User?

Yes, set the model option in the published footprints.php config to any Eloquent model, and implement TrackableInterface plus the TrackRegistrationAttribution trait on that model.

How do I keep the visits table from growing too large?

Schedule the footprints:prune Artisan command daily. By default it removes entries unassigned to a user that are older than attribution_duration, and you can override this with the --days option (for example --days=10). You can also enable robot tracking exclusion to keep bots out of the table.

Does Footprints work if cookies are disabled?

Yes, set uniqueness => false in the config so the footprint is computed from the IP address and the User-Agent header instead of relying on the footprints cookie.