Facebook Conversion API (CAPI)

Send the pixel events directly to Facebook’s servers, bypassing browser limitations or ad blockers

How to setup CAPI events with PixelYourSite and how to test them

or

Conversion API (CAPI)

Conversion API allows your website to send events directly to Facebook’s servers. These events are linked to your pixel and are processed by Facebook like browser events.

The main advantage of CAPI events is that they will bypass browsers’ limitations or ad blockers.

How to configure CAPI with PixelYourSite

Get the token

Go to Events Manager

Select the pixel you want to configure and click on Settings

Scroll down until you see “Conversion API” and click on “Generate Access Token”.

Copy the token by clicking on it.

Add the token to PixelYourSite

Open your PixelYourSite plugin and add the token in the dedicated field under the Pixel ID. Check the option to send CAPI events, scroll the page, and SAVE.

PixelYourSite will start to send CAPI events along with the browser events. As a final step, you should delete any cache that might be present on the website. This will ensure that the latest version of the code is served immediately to your users.

How to test CAPI events

To test CAPI events, go inside your Events Manager.

Click on Test Events and copy the Test Code.

Open the PixelYourSite plugin and add the text code in the dedicated field below the pixel ID. Scroll the page, and save. If you have a cache plugin, delete your cache. 

Start browsing your website to fire events. 

Make sure you don’t test with an excluded role. You have this option on the plugin’s main page. 

Go back to Events Manager, and you will see events reported under Testing.

You’ll start to see pairs of browser and server events, with the server events deduplicated. 

Click on the event to see its parameters or its Event ID.

Only browser events fired in the browser window where the Events Manager is open are reported under testing. If you browse your website in an incognito window or in a different browser, browser events are recorded, but not reported. In this case, you will see only the deduplicated server events.

To see active server events, install an ad blocker and browse your website. Facebook will get only the server events, so it won’t deduplicate them.

It’s possible to see warnings from time to time. Some of these warnings can be false positives. We noticed warnings related to missing travel parameters for events that have nothing to do with travel.

When you are done testing, remove the testing code from PixelYourSite. 

CAPI events are a backup for the browser events

Conversion API events don’t replace browser events, they work as a backup. If for some reason the browser events don’t work, Facebook will use the CAPI events.

It means that every event is in fact sent twice, once using the browser, once using Conversion API.

Deduplicating events

In order to keep your events reporting accurate, Facebook is deduplicating server events when a browser event is sent. Deduplication means that when both browser and server events are received, the browser event is processed, and the server event is dropped.

Event ID

When deduplicating events, Facebook uses two important signals: the event name and the Event ID. When a pair of server and browser events have the same name and the same ID, the server event is deduplicated.

PixelYourSite always ads an unique Event ID for every pair of browser-server events.

Deduplicate events and cache

The key element of event deduplication is the Event ID. this must be unique to each pair of browser/server events. 

Cache problem

Sometimes cache plugins will store the full code of a page, including the Event ID. It means that when the page is visited by different users, the same event IDs will be delivered again and again. For Facebook, these events might look connected, and disregarded as such. 

The solution

To overcome this problem PixelYourSite user admin-ajax, bypassing caches this way. 

You can enable or disable the use of admin-ajax from the plugin’s main page.

If you disable admin-ajax, it’s best to check if the Event ID is indeed unique to each pair of events. 

Test the Event ID

You can do it using the Pixel Helper Chrome extension, or the Events Manager testing tool

Open a page in an incognito window. Check an event with Pixel Helper and look for its Event ID. Refresh the page and check the same event. If the Event ID is different, you are fine. It means that the Event ID is not cached and deduplication works correctly.

Remember that Pixel Helper only shows the browser events, but for this test, this is enough. Down on this page, you will learn how to test server events too.

CAPI events data

Parameters

When sending CAPI events, PixelYourSite tries to send the same set of events parameters as for browser events. The only parameters we can’t collect are related to the visitor’s browser time, so these are sent for browser events only.

Match Key and User Data Keys

CAPI events also send additional information that helps Facebook match the user to a Facebook account.

Browser ID, Facebook Clik ID (FBC), Facebook Browser ID (FBP) are collected using Facebook’s own library. These are called Match Keys.

When possible, the events also have data about your user, like Email, First Name, IP Address, Last Name, Phone, City State, ZIP code. These are called User Data Keys.

The plugin can send User Data Keys when the visitor is logged on your website, and there is data associated with the WordPress account. WooCommerce and Easy Digital Downloads Purchase event can take it from the order’s details.

Event Match Quality

Using Match Keys and User Data Keys, Facebook tries to match events to a Facebook account.

Because Purchase events have access to better User Data Keys, you can expect a better Matching Score for them. Events fired by non-logged-in visitors can have a lower score.

Diagnostics

From time to time, you will see some errors related to CAPI events reported under the Diagnostics tab.  Sometimes these errors are false positives or can be ignored.


Server Sending Invalid Match Key Parameters for Event

Your server is sending an invalid fbp, ip_address, user_agent parameters value for your event. This may be because there was an error in the parameter value.
This may cause issues with the attribution and delivery optimization of ad campaigns that are using this event.

We’ve seen this error from time to time. It’s probably caused by bots triggering the pixel, where the script can’t correctly identify fbp, ip_address, user_agent values.

It’s marginal, and you can ignore it.


Same Event ID Received for Many Event Instances

You’re sending the same event ID for many instances of your events. Event IDs are unique identifiers that are used to deduplicate identical events received from your pixel and the Conversions API so they’re not counted twice. To ensure Facebook is accurately counting your events, each unique event instance needs its own unique event ID.
This may cause issues with the measurement of your events and the attribution of your ad campaigns.

This can be indeed related to the cache issue explained before. Test your events and make sure each browser/server event has a unique Event ID.

Another possible explanation is that the page source was copied and served by other websites. This can be Google’s cache, Google Translate, or something else. You can restrict the pixel to fire on your domain only from the Events Manager Settings page. Look for Traffic Permissions and create an Allow List.

It can also be just a false positive.

Test and confirm that Event ID is unique to each pair of browser/server events and restrict the pixel to your domain only. Once you do these, you can ignore the problem.


 
New Domains Sending Data

Your pixel recently started sending events from these domains

This might or might not be an error. The solution is to create an Allow List with domains that can use the pixel.

Go to Events Manager, click on Settings, look for Traffic Permissions, and create an Allow List.

iOS 14 privacy update and your Facebook Pixel​
Learn about Facebook Aggregated Event Measurement
Learn about PixelYourSite V8
Verifying your Domain on Facebook using PixelYourSite
The Signal event & Facebook Custom Audiences or Custom Conversions
The Signal event & Aggregated Event Measurement
Facebook Conversion API (CAPI)