Documentation

What you need

• Statamic 6.20 or later, on PHP 8.3 or later.
• Composer on the server or in your deployment.
• Accounts with the ad platforms you use: a Meta dataset (Pixel), a GA4 property, a TikTok pixel.
• Statamic Core or Pro. Cargo is optional, for orders.

Install

1. In the folder where your site is installed, run:

composer require karelialabs/statamic-conversions

2. Buy a licence on the Statamic Marketplace and attach it to your site in your statamic.com account, as with any paid addon. Local and staging copies of the site need no licence.

Conversions appears under Tools in the Control Panel. Then follow the setup below: tokens in .env, settings, the script tag and your cookie banner.

Setup

1. Secrets go in .env

Control Panel settings are saved in resources/addons and usually end up in git, so access tokens never go there:

KARELIA_CONVERSIONS_META_ACCESS_TOKEN=...
KARELIA_CONVERSIONS_GA4_API_SECRET=...
KARELIA_CONVERSIONS_TIKTOK_ACCESS_TOKEN=...

Where to get them:

• Meta: Events Manager > your dataset (Pixel) > Settings > Conversions API > Generate access token.
• GA4: Admin > Data streams > your web stream > Measurement Protocol API secrets > Create.
• TikTok: TikTok Ads Manager > Events > Web events > your pixel > Settings > Events API > Generate access token.

The IDs (Meta Pixel ID, GA4 Measurement ID, TikTok pixel code) can go in .env too (KARELIA_CONVERSIONS_META_PIXEL_ID, KARELIA_CONVERSIONS_GA4_MEASUREMENT_ID, KARELIA_CONVERSIONS_TIKTOK_PIXEL_CODE) or in the settings.

2. Settings

Open Tools > Addons > Karelia Conversions:

• Platforms: switch each platform on or off and add the IDs. Add a test event code while you test.
• Events: add the forms that count as conversions, and what to send for each: Lead, Contact, Sign-up or a custom event, with an optional value and currency. Sign-ups and Cargo orders are on by default.
• Consent: "Only after consent" (default) or "Always".

3. Add the script to your layout

<head>
    {{ conversions:script }}
    ...
</head>

It keeps UTM tags and click IDs from the landing page in a first-party cookie, but only after consent. It works on statically cached pages too.

4. Connect your cookie banner

When the visitor accepts marketing cookies:

KareliaConversions.consent(true);

and when they withdraw consent:

KareliaConversions.consent(false);

Or let the addon read the cookie your banner already writes. Choose your banner under Settings → Consent → Cookie banner:

For another banner, choose Another banner, enter its cookie name, and the Accepted value:

• a key and value, such as marketing:true. It matches marketing:true, "marketing":true and marketing=true, and a cookie that says marketing:false, "marketing":false or marketing=no never counts;
• or the exact cookie value, such as allow or 1. The whole cookie must equal it.

The value is never matched as "contains", because many banners write every category whether it was accepted or not. Banners that only list the accepted categories (for example "categories":["necessary","marketing"]) are best connected with KareliaConversions.consent(true) from the banner's own "accepted" callback.

For sites that need no consent, choose Always.

5. Test

• Open Tools > Conversions and press Send test event on each platform. Meta's and TikTok's test events show up under Test Events in their event managers; GA4 is checked against Google's validation endpoint.
• Or from the command line: php please conversions:test (or conversions:test meta).
• Then send one of your forms and watch it appear in the log.

Remove the test event codes when you are done.

Google Ads

Karelia Conversions sends to GA4. To count the conversions in Google Ads, link GA4 and Google Ads, mark the events (generate_lead, sign_up, purchase) as key events in GA4 (Admin > Events), and import them in Google Ads (Goals > Summary > Create conversion action > Google Analytics). See Google's help article "Create conversions from Google Analytics events in Google Ads". Imports can take up to 24 hours.

Events

Every conversion gets one event ID that is the same on all platforms.

Sending conversions from your own code

use KareliaLabs\Conversions\Conversion;
use KareliaLabs\Conversions\Conversions;

app(Conversions::class)->track(
    Conversion::make('lead')
        ->fromRequest(request())
        ->user(['email' => $email, 'phone' => $phone, 'first_name' => $first, 'last_name' => $last])
        ->value(120, 'EUR')
        ->source('booking', 'demo', $booking->id, 'Demo booking')
);

fromRequest() fills in the page, IP address, browser, click IDs and consent. Events are lead, contact, sign_up, purchase and custom (with a name: Conversion::make('custom', 'Book a demo')).

To decide consent in code instead of with a cookie:

\KareliaLabs\Conversions\Consent::resolveUsing(fn ($request) => $request->user()?->get('marketing_consent') === true);

Cargo orders

Payment is often confirmed by a webhook from the payment provider, so the request that marks an order paid is not the shopper's. When the shopper has given consent, Karelia Conversions therefore keeps their details (IP address, browser, click IDs) in the cache for up to 14 days from checkout, and uses them when the order is paid. Without consent it keeps only the fact that consent was not given. Amounts are converted from Cargo's minor units, and the currency comes from the site.

What is sent, and what is kept

• Sent: the event, its time and ID, the page address, the visitor's IP address and browser, the click IDs and first-party cookies the platforms set themselves (_fbp, _fbc, _ga, _ttp), value, currency and products.
• Sent hashed with SHA-256: email, phone and user ID to all three; first and last name to Meta and Google Analytics 4; city, postcode and country to Meta. TikTok receives no name or address.
• Sent in plain text: city, postcode and country to Google Analytics 4, because its Measurement Protocol only accepts them that way. Leave those fields out of your forms if you do not want that.
• Not sent: anything for visitors who have not given consent (in "Only after consent" mode).
• Kept on your server: a log line per conversion in storage/statamic/karelia-conversions, with the event, source, value, UTM source and campaign, click ID type and each platform's answer. No names, emails, phone numbers or IP addresses. Lines older than 30 days are deleted (configurable).
• Never sent to Karelia Labs. The addon has no telemetry and no licence server.

You remain the data controller for what you send to Meta, Google and TikTok. Mention it in your privacy policy.

Configuration

Publish the config file to change the defaults:

php artisan vendor:publish --tag=statamic-conversions-config

Permissions

• View conversions: see the log and the totals.
• Send test events: use the test buttons.

Good to know

• Karelia Conversions does not add the Meta Pixel, the GA4 tag or the TikTok pixel to your pages. If a form also fires a Lead in the browser Pixel, Meta counts both; keep form leads on the server only.
• GA4 ties the conversion to the visitor's session through the _ga cookie. Without the GA4 tag on your site, server-side events still arrive, but as separate users.
• The Measurement Protocol never reports errors on the live endpoint; use the test button (validation endpoint) to check your setup.