> For the complete documentation index, see [llms.txt](https://docs.rafflex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rafflex.io/marketing/facebook-and-meta/tracking.md).
# Tracking
Connect your Meta Pixel and Conversions API token so Meta can measure your ads accurately. RaffleX then sends visits, baskets, checkouts, sign ups and purchases to Meta for you.
Tracking lets Meta see what people do after they click your ad, such as viewing a competition, adding tickets to their basket or completing an order. With it set up, Meta can show you which ads actually bring in sales, build audiences from your visitors and buyers, and automatically show your ads to the people most likely to enter.
RaffleX has Meta tracking built in. You only need to paste in two details from your Meta account, and RaffleX takes care of the rest. There is no tracking code to install.
***
### Before you start
You will need:
* A **Meta Business account** (also called Business Manager or Business Portfolio) at [business.facebook.com](https://business.facebook.com).
* A **Pixel** (Meta also calls this a **dataset**) created in **Events Manager**. If you do not have one yet, open Events Manager and follow Meta's steps to connect a new **web** data source. When Meta asks how you want to install it, you can stop once the Pixel has been created, because RaffleX installs it for you.
{% hint style="warning" %}
**Do not add the Meta Pixel code anywhere else on your site.** If you also paste Meta's Pixel code into **Header Code** or load it through Google Tag Manager, every event will be counted twice and your reports will be wrong. Just use the fields on this page.
{% endhint %}
***
### Find the Facebook Analytics settings
1. In the **admin panel**, click **Settings** in the left-hand menu.
2. In the Settings side menu, click **Marketing**. The page title reads **Marketing & Social**.
3. Scroll down to the **Facebook Analytics** section. Its description reads "Connect Meta Pixel and Conversions API credentials for event tracking."
The section has three settings:
| Setting | What it is for |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| **Facebook Pixel ID** | Switches on Meta tracking in your customers' browsers. This is the one you must fill in. |
| **Facebook Conversion Access Token** | Also sends your most important events straight from RaffleX to Meta (the Conversions API). Strongly recommended. |
| **New Customer FBQ Purchase Event** | Optional. Sends an extra custom event when a customer places their first paid order. Off by default. |
***
### Step 1: Add your Facebook Pixel ID
The Pixel is the link between your website and your Meta account. Once you give RaffleX your Pixel ID, the Pixel is added to every page of your site automatically.
The field's helper text reads "Found in your Facebook Business Manager under Events Manager > Data Sources". To find it:
1. Go to [business.facebook.com](https://business.facebook.com) and open your Meta Business account.
2. From the left-hand menu, open **Events Manager**.
3. Under **Data Sources**, choose the Pixel you want to use.
4. Click the **Settings** tab at the top of the page. Your **Pixel ID** (sometimes shown as **Dataset ID**) is listed near the top. It is a long number.
5. Copy the number.
6. Back in RaffleX, paste it into the **Facebook Pixel ID** field.
{% hint style="info" %}
Paste only the number. Do not paste Meta's whole Pixel code snippet into this field. Do not worry about accidental spaces before or after the number, because RaffleX removes them when you save.
{% endhint %}
***
### Step 2: Add your Conversions API token (recommended)
The Conversions API sends your key events directly from RaffleX to Meta, rather than relying only on the customer's browser. Ad blockers, privacy settings and some phone browsers can stop the browser Pixel from reporting, so adding the token means far fewer sales go missing from your ad reports.
The field's helper text reads "Found in your Facebook Business Manager under Events Manager > Data Sources > Settings. Scroll down to Conversions API and click Generate Access Token." Step by step:
1. Go to [business.facebook.com](https://business.facebook.com) and open **Events Manager**.
2. Under **Data Sources**, choose the **same Pixel** whose ID you entered in Step 1.
3. Click the **Settings** tab at the top of the page.
4. Scroll down to the **Conversions API** section and click **Generate Access Token**.
5. When the token appears, copy all of it. It is a very long string of letters and numbers.
6. Back in RaffleX, paste it into the **Facebook Conversion Access Token** field.
{% hint style="danger" %}
Treat your access token like a password. Do not share it in emails, screenshots or social posts. If you think it has been seen by someone else, generate a new one in Events Manager and paste the new token into RaffleX.
{% endhint %}
***
### Step 3: Save and check for errors
Click **Save Settings** at the bottom of the page.
* **If you only filled in the Pixel ID**, your settings save straight away and you will see **Marketing settings saved successfully**.
* **If you filled in both the Pixel ID and the access token**, RaffleX first checks them with Meta. If Meta accepts them, the settings save as normal.
* **If Meta rejects them**, a red **Facebook API Validation Failed** notice appears explaining why. **Nothing on the page is saved** until the problem is fixed, including any other Marketing settings you changed at the same time. The notice stays on screen until you close it.
{% hint style="warning" %}
This check happens every time you click **Save Settings** on the Marketing page while both Facebook fields are filled in. If your token stops working later (for example, because it was revoked in Meta), you will see this error even when you are only changing a different Marketing setting. Fix the token, or clear it, and then save again.
{% endhint %}
Common messages and what to do:
| Message | What it means and how to fix it |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Invalid access token. Please generate a new token from Facebook Events Manager. | The token was copied incompletely, has expired or was revoked. Generate a fresh token (Step 2) and paste the whole thing. |
| Invalid Pixel ID. Please verify the Pixel ID exists in your Facebook Events Manager. | The Pixel ID is mistyped, or that Pixel has been deleted. Copy the ID again from Events Manager. |
| The access token does not have permission to access this Pixel. | The token was generated for a different Pixel. Make sure you generate the token from the same Pixel whose ID you entered. |
| Unable to connect to Facebook. Please check your internet connection and try again. | RaffleX could not reach Meta at that moment. Wait a minute and click **Save Settings** again. |
Any other problem from Meta is shown with Meta's own explanation after "Facebook API error:". If you see "An unexpected error occurred while validating credentials.", try saving again in a few minutes. If you are stuck, contact Rafflex support.
{% hint style="info" %}
**Need to remove tracking?** Clear the **Facebook Pixel ID** field and click **Save Settings**. This stops all Meta tracking on your site. To stop only the Conversions API, clear just the **Facebook Conversion Access Token** field and save. The browser Pixel will carry on working on its own.
{% endhint %}
***
### What RaffleX sends to Meta
Once your Pixel ID is saved, RaffleX sends these standard Meta events automatically. You do not need to set any of them up.
| Event | When it is sent | Browser Pixel | Conversions API (with token) |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------: | :-----------------------------------: |
| **PageView** | Every time someone loads a page on your site. | Yes | No |
| **ViewContent** | When someone opens a competition page. Includes the competition, its ticket price and your currency. | Yes | No |
| **AddToCart** | When someone adds tickets to their basket. Includes the competition, the number of tickets and the value. | Yes | Yes |
| **InitiateCheckout** | When a customer opens the checkout page. Includes the basket value and number of items. | Yes | Yes |
| **Purchase** | When an order takes real money: a card or PayPal payment, or a Site Credit top up. The value is the money actually taken. Includes your currency and the competitions bought. | Yes, once per order on the order confirmation page | Yes, as soon as the order is complete |
| **FreeEntry** (custom event) | When a customer completes an order that cost nothing, such as a free competition, a free entry or a 100% discount code. Has no value. | Yes, once per order on the order confirmation page | Yes, as soon as the order is complete |
| **CreditSpend** (custom event) | When a customer pays for an order entirely with Site Credit. Has no value. The amount of credit spent is included separately. | Yes, once per order on the order confirmation page | Yes, as soon as the order is complete |
| **CompleteRegistration** | When a new customer creates an account on your site. | Yes | Yes |
**FreeEntry** and **CreditSpend** are **custom events**. These are events with a name RaffleX chooses, rather than one of Meta's built in standard events like Purchase. They appear in Events Manager on their own, with no setup needed.
#### How each type of order is reported
A **Purchase** means money came in, and its value is the money taken for that order. That way every real pound reaches Meta exactly once, and your ad reports show the revenue your ads actually brought in.
| Type of order | Event sent to Meta | Value reported |
| --------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------- |
| Paid by card or PayPal | **Purchase** | The order total |
| Paid partly by card and partly with Site Credit | **Purchase** | Only the part paid by card. The credit used is included separately, so it never counts as revenue. |
| Site Credit top up | **Purchase** | The amount the customer paid |
| Paid entirely with Site Credit | **CreditSpend** | None. The amount of credit spent is included separately. |
| £0 order (free competition, free entry or 100% discount code) | **FreeEntry** | None |
| Winlink prize tickets, and entries Club members receive automatically | Nothing is sent | |
{% hint style="info" %}
**Why an order paid with Site Credit is not a Purchase.** Site Credit is either money the customer already paid you when they topped up (which Meta has already counted as a Purchase), or credit you gave away, such as prizes, cashback or referral rewards. Counting the spend as well would report the same money twice, or report money you never received.
{% endhint %}
{% hint style="warning" %}
**Expect your reported Purchases to go down.** Before this change, free orders and orders paid with Site Credit were also sent to Meta as Purchases. Now they are reported as **FreeEntry** and **CreditSpend** instead, so the number of Purchases and the revenue in Ads Manager will drop, especially if you run free entry competitions or your customers spend a lot of credit.
**You are not losing any sales.** Your earlier figures were higher than the money you actually took. The new figures are the accurate ones, and your RaffleX **Orders** list is unchanged.
{% endhint %}
A few things worth knowing:
* **Events are not counted twice.** When an event is sent from both the browser and the Conversions API, both copies carry the same event name, the same details and the same event ID, so Meta recognises them as one event. This is called deduplication.
* **Orders are still recorded if the customer leaves early.** The browser copy of an order event fires when the customer reaches the order confirmation page. RaffleX makes sure it is not sent again if the customer refreshes that page straight afterwards. With the access token added, the server copy is sent as soon as the order completes, so the order still reaches Meta if the customer closes their browser before the confirmation page loads.
* **Better matching for your customers.** When a customer is signed in, or has already placed an order using the same browser, the Pixel shares their details (such as email address, name, phone number and postcode) with Meta in a scrambled, one way encoded form, known as **advanced matching**. Conversions API order events include similar details from the checkout form, along with details captured while the customer was on your site: their IP address (the internet address of their connection), their browser, their customer ID on your site and the page they placed the order from. This helps Meta match events to the right Facebook or Instagram user. You should see your **Event Match Quality** score in Events Manager improve as a result.
* **Competitions are identified consistently.** Events refer to each competition using the same ID that appears in your [Product Catalogue](/marketing/facebook-and-meta/product-catalogue.md) feed, so Meta can connect activity on your site to items in your catalogue for catalogue ads.
* **Only these events are sent.** Meta's own automatic event detection (which tries to guess events from button clicks) is switched off on RaffleX sites, so your Events Manager stays clean and only shows the events listed above.
{% hint style="info" %}
If a PCI compliance scan flags the `_fbp` cookie after you add your Pixel, that is a known false positive. See [Cookie Vulnerability (Facebook Pixel) False Positive](/helpful-info/pci-compliance-scan/pci-scan-cookie-false-positive.md) for an explanation and a response you can submit.
{% endhint %}
***
### Check that tracking is working
1. Open your website in a normal browser window (not a private window, and with any ad blocker paused).
2. Browse a competition, add some tickets to your basket and go to the checkout.
3. In Meta **Events Manager**, choose your Pixel and open the **Overview** tab.
4. Your **PageView**, **ViewContent**, **AddToCart** and **InitiateCheckout** events should start to appear. Meta can take a little while to show new activity, so check back later if nothing shows straight away.
Once you have taken a real paid order, you should also see **Purchase**. **FreeEntry** and **CreditSpend** appear the first time a customer places a free order or pays entirely with Site Credit. With the access token added, Events Manager also shows events arriving through the Conversions API (from the server) alongside the browser events.
{% hint style="success" %}
**Tip:** Meta's free **Meta Pixel Helper** extension for Google Chrome shows the events firing on each page as you browse your site. It is a quick way to confirm your Pixel is installed.
{% endhint %}
#### Test your order events with Meta's Test Events tool
Meta's **Test Events** screen shows each event the moment it arrives, so you can place a test order and see exactly what Meta received. To see the events sent from RaffleX's server (the Conversions API), your site needs a **test event code** from Meta.
1. Go to [business.facebook.com](https://business.facebook.com) and open **Events Manager**.
2. Under **Data Sources**, choose your Pixel.
3. Click the **Test Events** tab at the top of the page.
4. Find the test code Meta shows for server events. It is a short code that starts with **TEST**, for example **TEST12345**. Copy it.
5. Contact Rafflex support and ask them to add this code to your site's **Facebook Test Event Code** setting. This setting is managed by the support team, so you will not find it in your own Settings pages.
6. Once support confirms it is in place, keep the **Test Events** tab open and place a test order on your site. Try a small card order, and if you like, a free order and an order paid entirely with Site Credit too.
7. Watch the **Test Events** tab. Each order should appear with the event name and value from the table in [How each type of order is reported](#how-each-type-of-order-is-reported). Where an event arrived from both the browser and the server, Meta shows that it was deduplicated (counted once).
8. When you have finished, ask support to remove the test event code again. Meta asks for the code to be used only while you are testing.
{% hint style="info" %}
**Do not see the browser events in Test Events?** The test event code only applies to events sent from RaffleX's server. To see browser events there too, use the option on the **Test Events** tab to enter your website address and open it from there, then place your test order in that browser window. Meta changes its menus from time to time, so the names on your screen may differ slightly.
{% endhint %}
***
### Use FreeEntry and CreditSpend in your campaigns
**FreeEntry** and **CreditSpend** arrive in Events Manager automatically, and you do not have to do anything with them. If you only optimise your ads for **Purchase**, you can leave them alone.
If you would like to **optimise a campaign** for free entries or credit spends, or **build an audience** from them, you first need to turn each one into a **custom conversion**. A custom conversion is a named action you create in Events Manager so Meta can use it when it decides who to show your ads to. Create one for each event you want to use.
{% stepper %}
{% step %}
#### Make sure Meta has received the event
Meta only lets you pick an event it has already received at least once. If you have not seen **FreeEntry** or **CreditSpend** in your Events Manager **Overview** yet, place a free order or an order paid entirely with Site Credit yourself, then wait a little while for it to show.
{% endstep %}
{% step %}
#### Open Custom conversions
Go to [business.facebook.com](https://business.facebook.com) and open **Events Manager**. In the left-hand menu, click **Custom conversions**, then click **Create custom conversion**.
{% endstep %}
{% step %}
#### Name it and choose the event
1. Give it a clear name, such as **Free Entry** or **Credit Spend**.
2. Under data source, choose the **same Pixel** you added to RaffleX.
3. Under conversion event, choose **FreeEntry** (or **CreditSpend**) from the list.
4. Leave the rules empty. You want every one of these events to count.
5. Choose the category that fits best. If you are not sure, choose **Other**.
6. Leave the conversion value empty. These events have no value on purpose, so that free entries and credit never count as revenue.
{% endstep %}
{% step %}
#### Create it
Click **Create**. Your new custom conversion appears in the list and becomes **Active** the next time the event arrives.
{% endstep %}
{% step %}
#### Use it in Ads Manager
When you build or edit a campaign in Ads Manager, choose your new custom conversion as the **conversion event** in the ad set. You can also create a **custom audience** of website visitors who triggered the event, for example to show a paid competition to people who have only entered your free ones.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
**Changing the event a campaign optimises for resets its learning.** Meta treats it almost like a new campaign and needs time (often around a week) to learn who to show your ads to again, and results can wobble while it does. Make the switch in a quiet week, not just before a big draw or launch.
{% endhint %}
***
### New Customer FBQ Purchase Event (optional)
This setting is for operators who want to target or measure **new** customers separately from existing ones. It is **off** by default.
The helper text in the admin panel reads:
> Advanced: Fires a custom Facebook Pixel event called "NewPaidCustomerPurchase" on a customer's first paid order only (card, PayPal or a Site Credit top-up; free and credit-only orders don't count). Requires setup in Facebook Events Manager to define the custom event before it can be used in audiences or rules. Useful for building lookalike audiences from new paying customers or excluding existing buyers from acquisition campaigns.
When the toggle is on, RaffleX sends an extra custom event called **NewPaidCustomerPurchase**, but only on the customer's **first order that took real money**:
* An order paid by card or PayPal counts, including one paid partly with Site Credit.
* A Site Credit top up counts, because that is when the customer first paid you.
* Free orders and orders paid entirely with Site Credit **never** count. A customer whose first few orders were free entries still triggers the event later, on their first paid order.
Their later orders send the normal **Purchase** event only. The custom event includes the same value as the matching Purchase (the money taken) and your currency.
The event is sent from the order confirmation page by the browser Pixel and, if you have added your **Facebook Conversion Access Token**, from RaffleX's server as well. Both copies carry the same event ID, so Meta counts it once, and it still reaches Meta if the customer closes their browser early or uses an ad blocker.
The browser copy does not include the customer's email address, phone number or postal address. Meta does not allow personal details like these to be sent as plain text inside an event. Meta can still match the event to the right person through the scrambled details described in [What RaffleX sends to Meta](#what-rafflex-sends-to-meta).
Good uses for it:
* **Lookalike audiences.** Ask Meta to find more people similar to your newest paying customers.
* **Excluding existing buyers.** Keep "first order" offers away from people who have already bought from you.
* **Measuring acquisition.** See how many brand new customers each campaign brings in, separately from repeat orders.
To use it:
1. In the **Facebook Analytics** section, switch on **New Customer FBQ Purchase Event**.
2. Click **Save Settings**.
3. Wait until at least one new customer has completed their first paid order, so Meta has received the event.
4. In Meta **Events Manager**, set up the custom event so you can use it. For example, create a **custom conversion** based on the **NewPaidCustomerPurchase** event (follow the same steps as in [Use FreeEntry and CreditSpend in your campaigns](#use-freeentry-and-creditspend-in-your-campaigns), choosing **NewPaidCustomerPurchase** as the event), or create a **custom audience** of website visitors who triggered it.
5. Use that custom conversion or audience in Ads Manager when you build your campaigns.
{% hint style="info" %}
This event works with just your **Facebook Pixel ID**, and also uses the Conversions API once your access token is saved. It is sent in addition to the normal **Purchase** event, not instead of it, so your purchase reporting is not affected.
{% endhint %}
***
### Tracking other ad platforms
Want to track conversions on other ad platforms such as TikTok or Google Ads? See [Conversion Event Tracking](/advanced/conversion-event-tracking.md) for the more advanced setup. You do not need to do anything extra for Meta, because the events above are already sent for you.
