Ad Pixels

Meta, TikTok and LinkedIn pixels on the site's pages.

kitloom/ad-pixels · admins: kitloom/ad-pixels-filament, kitloom/ad-pixels-nova

Video lessons

Recorded in the Filament admin; the Nova admin works the same way.

Ad Pixels Settings

The ad networks' pixels on the site's pages: Meta (Facebook and Instagram), TikTok and the LinkedIn Insight Tag. Ads can then be measured, and site visitors can be found again in the networks' audiences. It does what the networks' own WordPress plugins or PixelYourSite did on the WordPress site, and their pixel IDs can be imported. The admin page is the Ad Pixels section (kitloom/ad-pixels-filament or kitloom/ad-pixels-nova).

Setting it up

Open Ad Pixels → Settings and fill in the IDs of the networks you advertise on. An empty ID means that pixel is off.

Pixel	What to enter	Where to find it
Meta	The pixel (dataset) ID, digits	Meta Events Manager → Data sources
TikTok	The pixel code, C…	TikTok Ads Manager → Assets → Events → Web events
LinkedIn	The partner ID, digits	Campaign Manager → Analyze → Insight Tag

Every page of the theme gets:

• each pixel's base code with its page view, where the theme put @siteHead;
• for visitors without JavaScript, Meta's and LinkedIn's image right after <body> (@siteBodyOpen).

In an Inertia theme, the next page opens without a reload:

• Meta and TikTok are sent a page view for it by the module.
• LinkedIn's tag has no page-view call to repeat, so it counts the first page.

Shop sales

With the shop module, the pixels also receive the shop's sales as their networks' standard events:

Shop	Meta	TikTok
A product page is opened	ViewContent	ViewContent
A product goes into the cart	AddToCart	AddToCart
The checkout form is opened	InitiateCheckout	InitiateCheckout
The "order received" page is shown	Purchase	CompletePayment

Each event carries the products (by the product's ID), the value and the currency. A purchase also carries the event ID purchase-{order number}, so a server-side event for the same order can be matched to it later. Each order is sent once per browser. A failed or cancelled order is not sent.

LinkedIn conversions are set up in Campaign Manager, by URL (the "order received" page) or by event.

Consent

Ad pixels are marketing. With the Cookie Consent module installed, each pixel waits until the visitor agrees to marketing. The images for visitors without JavaScript are left out: without JavaScript there is nobody to ask. Without a consent module, the pixels load at once.

Who is tracked

Signed-in users (editors, administrators, customers with an account) are not tracked by default, so the site's own people do not end up in the ad audiences. Track signed-in users turns that off. Pages for guests are cached as before: a signed-in user's page is always drawn anew, so leaving the pixels out of it affects nobody else.

Coming from WordPress

If the WordPress site had one of these plugins, the settings page shows an Import button. The console command does the same:

php artisan ad-pixels:import
php artisan ad-pixels:import --from=meta --from=tiktok

Plugin	What is taken
Meta pixel for WordPress	The pixel of its current connection, otherwise of its older settings
TikTok	The pixel code
LinkedIn Insight Tag	The partner ID, if the tag was on. A pasted snippet works too.
PixelYourSite	The first Meta pixel, if its Meta pixel was on (from its own pys_options table, or from the options)

Only the IDs are taken. Not carried over:

• Server-side tokens (Meta's Conversions API, TikTok's Events API). They stay where they are: this module sends nothing from the server.
• Advanced matching (visitors' emails sent to the networks).
• Events beyond the page view and the shop's sales, such as leads.

The plugins' own settings are not touched.

For developers

• Settings: ad_pixels_*, declared by AdPixelsOptions and written through SettingWriter. An ID that does not look like one is never put into a page.
• How the pixels reach the page:
  • AdPixelsScripts is the PageScriptsProvider.
  • Each network is a Pixels\Pixel, with its head code and its image.
  • Both go through kitloom/site's ScriptConsent::gate() as marketing.
• CSP: a nonce set with Vite::useCspNonce() goes on the scripts.
• Config: php artisan vendor:publish --tag=kitloom-ad-pixels-config publishes the admin sections switch.
• Tests, from the application that installs the package: php vendor/bin/phpunit --testsuite AdPixels.