Download the PHP package electrictomcat/laravel-google-ads-conversions without Composer

Laravel Google Ads Conversions

Drop-in offline conversion tracking for Laravel apps using Google Ads.

• Captures gclid (and gbraid/wbraid) from incoming traffic and persists it across the visitor's session
• Records conversion events with a one-line API
• Buffers in cache, syncs to your database, and uploads to Google Ads in batched, queued jobs
• Honors Google Ads' minimum reporting delay (default 6 hours)
• Bring-your-own model — implement a small contract or use the included Lead model out of the box
• Supports both call-site values (record('Event', 100)) and config-mapped defaults

Status: pre-release. Not yet on Packagist.

Installation

Publish the config and the migration:

Add these to your .env (see Google's OAuth setup for how to mint the refresh token):

Register the middleware in bootstrap/app.php:

Schedule the upload job in routes/console.php:

Usage

Recording a conversion

From anywhere in your app — controllers, jobs, Livewire components, observers:

The first argument is your internal event name. The second is an optional value. The full signature is:

Mapping events to Google Ads conversion actions

Edit config/google-ads-conversions.php. Each event entry is either a string (just the action name) or an array with optional value/currency defaults:

The call site always wins — record('Demo Booked', 999) overrides the config's 250.00. Omit the value at the call site to use the config default.

Bring your own model

The package ships a Lead model and matching migration that work out of the box. If you'd rather use your own model — say, you already have a Visitor table and want to track conversions there — implement the HasConversions contract.

The fastest path: drop the HasConversionsTrait onto your existing model:

Make sure your table has at minimum these columns:

• gclid (string, unique, indexed)
• visitor_id (uuid, nullable)
• conversions (json, nullable)

Then point the package at it:

For full control, implement HasConversions from scratch — see src/Contracts/HasConversions.php for the contract.

How the pipeline works

1. Middleware (CaptureGclid) — runs on the landing request, extracts gclid from the URL, sets cookies + session, buffers a stub lead record in cache.
2. Recording (GoogleAdsConversions::record()) — pushes a conversion entry into a per-gclid cache bucket. Cheap. Fire from anywhere, including HTTP requests where the user has no gclid on the URL but does have one in their session/cookie.
3. Sync (syncToDatabase()) — flushes the cache buffer into the configured model's table. Runs as the first half of the queued job.
4. Upload (uploadPendingConversions()) — finds every pending conversion older than the delay window and ships eligible batches to Google Ads via UploadClickConversions. Marks each shipped conversion as 'uploaded' with a timestamp.

Testing

The suite uses Pest 4 + Orchestra Testbench against an in-memory SQLite database.

Changelog

See CHANGELOG.md.

Contributing

Issues and pull requests welcome.

Credits

• Tom Michael
• Built on top of the Spatie package skeleton and googleads/google-ads-php

License

The MIT License (MIT). See LICENSE.md.