Conversion Event Tracking

This guide is for AI assistants helping RaffleX tenants add third-party conversion tracking (TikTok, Google Ads, etc.) to their site. All code goes in Settings > Advanced > Header Code, which injects into the <head> of every page.

RaffleX exposes JavaScript hooks for two commerce events: AddToCart and Purchase. The sections below explain how to listen for each event and fire the appropriate tracking call for each platform.

Prerequisites

The ad platform's base pixel or tag must be installed in Header Code before any event tracking will work.

• Facebook: No action needed. RaffleX automatically installs the Facebook Pixel and fires all events (including AddToCart and Purchase) via both browser pixel and server-side Conversions API. Do not add duplicate fbq calls or events will double-count. For more on the built in Meta integration, see Facebook and Meta tracking.

• TikTok: The TikTok base pixel script must be added to Header Code, including the ttq.install('YOUR_PIXEL_ID') call. Get the pixel code from TikTok Ads Manager > Events > Website Pixel > Manage.

• Google Ads: The gtag.js script must be loaded in Header Code with the Google Ads conversion ID (e.g., AW-XXXXXXXXX). Get the tag from Google Ads > Goals > Conversions > the specific conversion action. If you also want general visitor analytics, see Google Analytics and UTM tags.

---

AddToCart

Fires when a user adds tickets to their cart from a product page. Does not fire for upsell additions.

Hook

Livewire.on('addtobasket', (event) => {
    // Your tracking code here
});

Available Data

Property	Type	Description
event.productId	number	The product/competition ID
event.productPrice	number	Price per ticket
event.tickets	number	Number of tickets added (quantity)
event.content	string	Product title
event.fbEventId	string	Facebook event ID for deduplication

TikTok

<script>
Livewire.on('addtobasket', (event) => {
    if (typeof ttq !== 'undefined') {
        ttq.track('AddToCart', {
            content_id: event.productId.toString(),
            content_name: event.content,
            content_type: 'product',
            quantity: event.tickets,
            value: parseFloat((event.productPrice * event.tickets).toFixed(2)),
            currency: 'GBP'
        });
    }
});
</script>

Replace 'GBP' with the tenant's currency code (e.g., 'USD', 'EUR'). Currency must be uppercase.

Google Ads

<script>
Livewire.on('addtobasket', (event) => {
    if (typeof gtag === 'function') {
        gtag('event', 'add_to_cart', {
            currency: 'GBP',
            value: parseFloat((event.productPrice * event.tickets).toFixed(2)),
            items: [{
                item_id: event.productId.toString(),
                item_name: event.content,
                quantity: event.tickets,
                price: event.productPrice
            }]
        });
    }
});
</script>

Replace 'GBP' with the tenant's currency code.

Facebook (Reference Only)

RaffleX already fires this event automatically via both browser pixel and server-side CAPI. The code below is for reference only. Do not add this to Header Code or it will cause duplicate events.

// ALREADY HANDLED AUTOMATICALLY - DO NOT ADD
fbq('track', 'AddToCart', {
    content_name: event.content,
    content_type: 'product',
    content_ids: [event.productId.toString()],
    value: parseFloat((event.productPrice * event.tickets).toFixed(2)),
    currency: 'GBP',
    num_items: event.tickets
}, {
    eventID: event.fbEventId
});

---

Purchase

Fires once per order on the thank you page. RaffleX pushes a purchase event to window.dataLayer containing full order data. Since Header Code loads in <head> before the body scripts, it can intercept this push.

Hook

The pattern below overrides dataLayer.push to intercept the purchase event. Place this in Header Code and it will automatically catch the event when it fires on the thank you page.

window.dataLayer = window.dataLayer || [];
(function() {
    var originalPush = Array.prototype.push;
    window.dataLayer.push = function() {
        originalPush.apply(this, arguments);
        for (var i = 0; i < arguments.length; i++) {
            if (arguments[i] && arguments[i].event === 'purchase' && arguments[i].ecommerce) {
                onPurchase(arguments[i].ecommerce);
            }
        }
    };
})();

function onPurchase(data) {
    // Your tracking code here
    // data.transaction_id - order ID
    // data.value - order total (number)
    // data.currency - e.g. "GBP"
    // data.items - array of { item_name, item_id, quantity, price }
}

Available Data

Property	Type	Description
data.transaction_id	string	The order ID
data.value	number	Order total
data.currency	string	Currency code (e.g., "GBP")
data.items	array	Order items
data.items[].item_name	string	Product title
data.items[].item_id	number	Product ID
data.items[].quantity	number	Number of tickets
data.items[].price	number	Price per ticket

TikTok

<script>
window.dataLayer = window.dataLayer || [];
(function() {
    var originalPush = Array.prototype.push;
    window.dataLayer.push = function() {
        originalPush.apply(this, arguments);
        for (var i = 0; i < arguments.length; i++) {
            if (arguments[i] && arguments[i].event === 'purchase' && arguments[i].ecommerce) {
                var data = arguments[i].ecommerce;
                if (typeof ttq !== 'undefined') {
                    var contentIds = data.items.map(function(item) {
                        return item.item_id.toString();
                    });
                    ttq.track('CompletePayment', {
                        content_ids: contentIds,
                        content_type: 'product',
                        quantity: data.items.reduce(function(sum, item) { return sum + item.quantity; }, 0),
                        value: data.value,
                        currency: data.currency
                    });
                }
            }
        }
    };
})();
</script>

Note: TikTok uses CompletePayment as the event name for purchases, not Purchase.

Google Ads

If Google Ads conversion tracking is set up via gtag.js, RaffleX already fires gtag('event', 'purchase', ...) on the thank you page. No additional code is needed unless you want to fire a specific conversion action.

To fire a specific Google Ads conversion action:

<script>
window.dataLayer = window.dataLayer || [];
(function() {
    var originalPush = Array.prototype.push;
    window.dataLayer.push = function() {
        originalPush.apply(this, arguments);
        for (var i = 0; i < arguments.length; i++) {
            if (arguments[i] && arguments[i].event === 'purchase' && arguments[i].ecommerce) {
                var data = arguments[i].ecommerce;
                if (typeof gtag === 'function') {
                    gtag('event', 'conversion', {
                        send_to: 'AW-XXXXXXXXX/CONVERSION_LABEL',
                        value: data.value,
                        currency: data.currency,
                        transaction_id: data.transaction_id
                    });
                }
            }
        }
    };
})();
</script>

Replace AW-XXXXXXXXX/CONVERSION_LABEL with the tenant's Google Ads conversion ID and label.

Facebook (Reference Only)

RaffleX already fires this event automatically via both browser pixel and server-side CAPI with full deduplication. The code below is for reference only. Do not add this to Header Code.

// ALREADY HANDLED AUTOMATICALLY - DO NOT ADD
fbq('track', 'Purchase', {
    value: data.value,
    currency: data.currency,
    content_type: 'product',
    content_ids: data.items.map(item => item.item_id.toString()),
    num_items: data.items.reduce((sum, item) => sum + item.quantity, 0)
}, {
    eventID: 'order_' + data.transaction_id
});

---

Important Notes

• Facebook is automatic. RaffleX handles all Facebook Pixel events (PageView, ViewContent, AddToCart, InitiateCheckout, Purchase, CompleteRegistration) through both browser pixel and server-side Conversions API. Adding your own fbq calls will result in duplicate events and inflated reporting.

• Currency codes are always uppercase (e.g., GBP, USD, EUR). Match the currency configured in the tenant's settings.

• AddToCart only fires for direct cart additions, not upsell items added from the cart drawer.

• Purchase fires once per order. RaffleX uses a cache guard to prevent the event from firing on page refreshes or revisits to the thank you page.

• dataLayer interception must be set up in Header Code (which loads in <head>) so the override is in place before the thank you page body scripts execute.