Facebook Conversions API
The Facebook Conversions API allows advertisers to send events directly to Facebook via a server-side connection.
Server-side events are sent to Facebook via the Facebook Conversions API (formerly known as Facebook Server-Side API). The Facebook Conversions API enables you to measure events that may not happen in the browser, improve accuracy by tracking events both in the browser and on the server, and more.
- Connection Modes:
Client-side | Server-side | |
|---|---|---|
Web | ||
Mobile | ||
Server |
To set up the Facebook Conversions API integration, follow the following steps:
- 1.
- 2.In Facebook, go to Events Manager > Data Sources and find your Pixel ID and copy this value into your Freshpaint Facebook Conversions API destination:
- 3.To use the Facebook Conversions API, you'll need to generate an access token. Copy this value into your Freshpaint Facebook Conversions API destination:
That's it! You have successfully set up the Facebook Conversions API destination. Enable this destination for events you'd like to send.
When you send an event to Facebook from Freshpaint, Freshpaint will create an event in Facebook by hitting Facebook's event API endpoint at: https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}.
See below for a complete list of Facebook standard events, the Freshpaint event definitions they are mapped to, and the available properties that can be sent in with each event. All properties are optional unless otherwise noted as "Required".
Facebook Event | Freshpaint Event Definition | Available Facebook Properties |
|---|---|---|
AddToCart | AddToCart | content_ids, content_name, content_type, contents, currency, value |
| product added | |
| added product | |
AddToWishlist | AddToWishlist | content_name, content_category, content_ids, contents, currency, value |
AddPaymentInfo | AddPaymentInfo | content_category, content_ids, contents, currency, value |
CustomizeProduct | CustomizeProduct | `` |
Contact | Contact | |
CompleteRegistration | CompleteRegistration | content_name, currency, status, value |
Donate | Donate | |
InitiateCheckout | InitiateCheckout | content_category, content_ids, contents, currency, num_items, value |
| checkout started | |
| started checkout | |
Lead | Lead | content_category, content_name, currency, value |
Purchase | Purchase | Required: value, currency
Optional: content_ids, content_name, content_type, contents, num_items |
| | |
Schedule | Schedule | |
Search | Search | content_category, content_ids, contents, currency, search_string, value |
| products searched | |
| searched products | |
StartTrial | StartTrial | value, currency, predicted_ltv |
SubmitApplication | SubmitApplication | |
Subscribe | Subscribe | value, currency, predicted_ltv |
ViewContent | ViewContent | content_ids, content_category, content_name, content_type, contents, currency, value |
| product list viewed | |
| viewed product list | |
| product category viewed | |
| viewed product category | |
| product viewed | |
| viewed product | |
Facebook Events are case-sensitive
Any of the space-delimited names above are case-insensitive and may be alternatively delimited by an underscore or no separation. For example, "product added" can also be expressed as:
- Product_added
- productAdded
These non-Facebook-specific names can be useful when sending to multiple destinations, such as Facebook Conversion API and TikTok Ads, without requiring a Rename Transformation for one or both destinations.
Parameters are JSON-formatted objects that you can include when tracking standard and custom events. They allow you to provide additional information about your users and their actions.
Facebook requires every event sent to the Conversions API to have an
action_source parameter describing where the event came from. If action_source is "website" (the default value), then the user_agent and url properties are also required (these correspond to the client_user_agent and event_source_url properties described in facebook's documentation).action_source is set to "website" by default for server-side events. action_source should be included under properties on track events.Action source value | Description |
|---|---|
website | Conversion was made on your website. |
email | Conversion happened over email. |
phone_call | Conversion was made over the phone. |
chat | Conversion was made via a messaging app, SMS, or online messaging feature. |
physical_store | Conversion was made in person at your physical store. |
system_generated | Conversion happened automatically, for example, a subscription renewal that’s set on auto-pay each month. |
other | Conversion happened in a way that is not listed. |
client_user_agent is automatically set from the built-in $user_agent property, or by including the user_agent property on track events. The value should be the user agent of the browser where the event occurred.event_source_url is captured automatically for web events, but must be manually added by including the url property on server track events. The value should be the browser URL where the event occurred.If your Freshpaint account is set up in HIPAA Mode, the URL will be redacted by default because it may contain PHI. For example, if the URL of the event is
https://example.com/heart-conditions#treatments?user=alice then Freshpaint will send https://example.com/url-redacted-by-freshpaintWhen you send user actions to Facebook, Facebook will attempt to match those actions to a particular Facebook user. In most cases, you'll want to send additional user traits and Facebook parameters to improve the number of the events that are matched to a Facebook user. See Facebook's documentation on all of the parameters that Facebook Conversions API accepts.
User traits you can include as event properties to improve match rate include:
emailphonelast_namefirst_nameip_address(is automatically set from built-in$ipproperty, or fromip_addressproperty)user_agent
Read Facebook's documentation on how match quality for events helps deliver ads to people who are more likely to take the action you care about, and attribute those actions back to your ads.
You should include the
fbp and fbc parameters found on the browser whenever possible.The
fbp parameter can be found in the _fbp cookie, and the fbc parameter can be found in either the _fbc cookie or the fbclid query parameter. See Facebook's documentation for more information.Freshpaint events can be converted into one of Facebook's standard events. A popular use case would be to convert an existing conversion event into Facebook's Purchase event. The Conversions API creates a connection between your first-party customer data and the Meta systems that optimize ad targeting and help measure the results of your advertising efforts.
In the example below, we are going to transform an existing "Test Event" into one of Facebook's standard Purchase events.
To get started, create a new Transformation and select Standard Event. Next, select the existing Freshpaint event you want to transform and the destination you want to send it to:
Then, select the "Purchase" event from the list of standard mappings and click "Save" to go to the following step:
In the case of the Purchase event, your existing Freshpaint event will need the following event properties:
value(amount of the conversion)currency(USD, CAD, etc)
For this transformation, you'll see that the event will be sent to Facebook named as "Purchase" while converting the
value property type into a number and sending the currency property value in all uppercase characters as required by Facebook.
If a
currency property isn't sent with your conversion event and all of your conversions are in a single currency type such as USD, you can add a new transformation rule to send USD as a constant property for your conversion event:
As new instances of "Test Event" occur, the transformation would then send them to the Facebook Conversions API destination as standard Purchase events.
If a
currency property isn't sent with your conversion event and all of your conversions are in a single currency type such as USD, you can add a new transformation rule to send USD as a constant property for your conversion event:
As new instances of "Test Event" occur, the transformation would then send them to the Facebook Conversions API destination as standard Purchase events.
Finally, visit your Facebook Events Manager account and navigate to the Overview tab and confirm the Purchase event is in the list:
Note: events may take a few minutes to populate in this view.
There are a few different ways to implement conversion tracking with Freshpaint's Facebook Conversions API integration. It can complement tracking with your Facebook Pixel, or you can use it as a standalone integration. The option that's best for you depends on your specific goals with the Facebook Conversions API.
The following options are available:
By sending the same events from both the browser and the server, you can improve the accuracy of browser events by providing redundancy. Events that previously would've been lost (e.g. due to the Facebook Pixel being blocked or network errors) can still be captured using the Conversions API.
For this approach to work best, the same
external_id should be sent from both the browser and server. This can be done by enabling the "Use UserId or Anonymous Id as External Id" setting in the Facebook Pixel destination. By doing this, Freshpaint will use the User ID or Anonymous ID as the external_id both on the browser and for the Conversions API, enabling Facebook to better match users.You can also improve the match rate by including the additional parameters listed above.
When the same event is sent from both the browser and the server, the events must be deduplicated to avoid having the same event counted twice. For events to be deduplicated, event names must be the same, and the server event must arrive after the client event. In this case, the server event is discarded. If the server events is received first, no deduplication occurs.
For Facebook to deduplicate events correctly, the recommended "Use UserId or Anonymous Id as External Id" setting must be enabled, or the
fbp parameter must be included in server-side events.This approach is best when you have events that can't be captured in the browser, such as a separate payment system. This approach is also ideal when you want to include sensitive data that shouldn't be sent to the browser.
For this approach to work best, the same
external_id should be sent from both the browser and server. This can be done by enabling the "Use UserId or Anonymous Id as External Id" setting in the Facebook Pixel destination. By doing this, Freshpaint will use the User ID or Anonymous ID as the external_id both on the browser and for the Conversions API, enabling Facebook to better match users.You can also improve the match rate by including the additional parameters listed above.
In this approach, different events are sent from the browser and the server, so no deduplication is necessary.
This approach is best if you don't want to load the Facebook Pixel on your site, or if you want more control over what gets sent to Facebook.
When using just the Facebook Conversions API without including many properties normally collected in the browser, the match rate will likely be lower than if they were included.
The match rate can be improved by including the additional parameters listed above.
In this approach, different events are sent from the browser and the server, so no deduplication is necessary.
Last modified 15d ago