> For the complete documentation index, see [llms.txt](https://documentation.freshpaint.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.freshpaint.io/integrations/destinations/apps/facebook-pixel.md). # Facebook Pixel Client-side events are sent to Facebook via the Facebook Pixel. The Facebook Pixel enables you to measure events that happen in the browser. {% hint style="warning" %} Client-side only integrations cannot be used in HIPAA mode. {% endhint %} ## Destination Info * Accepts [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Connection Modes:
Client-sideServer-side
Webtruefalse
Mobilefalsefalse
Serverfalsefalse
## Getting Started To set up the Facebook Pixel Integration, follow the following steps: 1. Go to the Facebook Pixel[ configuration page](https://app.freshpaint.io/destinations/advertising/facebook-pixel) in Freshpaint and click "Configure". 2. In Facebook, go to Events Manager > Data Sources and find your Pixel ID and copy this value into your Freshpaint Facebook Pixel destination:
3. To use the Facebook Conversions API, you'll need to generate an access token. Copy this value into your Freshpaint Facebook Pixel destination:
That's it! You have successfully set up the Facebook Pixel destination. Enable this destination for events you'd like to send. ## Events When you send an event to Facebook from Freshpaint, Freshpaint will create an event in Facebook by hitting Facebook's [event API](https://developers.facebook.com/docs/graph-api) endpoint at:[ ](https://graph.facebook.com/%7BAPI_VERSION%7D/%7BPIXEL_ID%7D/events?access_token={TOKEN})[https://graph.facebook.com/{API\_VERSION}/{PIXEL\_ID}/events?access\_token={TOKEN}](https://graph.facebook.com/%7BAPI_VERSION%7D/%7BPIXEL_ID%7D/events?access_token={TOKEN})[.](https://graph.facebook.com/%7BAPI_VERSION%7D/%7BPIXEL_ID%7D/events?access_token={TOKEN}) ### Standard Facebook Events 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 | | {% hint style="info" %} Facebook Events are case-sensitive {% endhint %} 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. ### Facebook Custom Events You can also track your own custom events in Facebook, which also can be used to define [custom audiences](https://developers.facebook.com/docs/facebook-pixel/implementation/custom-audiences) for ad optimization. Custom events also support [parameters](https://developers.facebook.com/docs/meta-pixel/implementation/conversion-tracking/#parameters), which you can include to provide additional information about each custom event. ### Event Parameters Parameters are optional, 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. In Facebook, these are called [object properties](https://developers.facebook.com/docs/meta-pixel/implementation/conversion-tracking/). See Facebook's [documentation ](https://developers.facebook.com/docs/meta-pixel/implementation/conversion-tracking/)for a complete list of object properties and their definitions. #### Action Source `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 `client_user_agent` is set 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 `event_source_url` is captured automatically for web events. The value should be the browser URL where the event occurred. ### Additional Parameters When 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](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc) to improve the number of the events that are matched to a Facebook user. See [Facebook's documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters) on all of the parameters that Facebook accepts. #### User Traits User traits you can include in the event props to improve match rate include: * `email` * `phone` * `last_name` * `first_name` * `ip_address` * `user_agent` #### Facebook Parameters {% hint style="warning" %} You should include the `fbp` and `fbc` parameters found on the browser whenever possible. {% endhint %} 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](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc) for more information. ## Configuration Options ### Transformations #### Converting Freshpaint Events Into Facebook Standard Events Freshpaint events can be converted into one of Facebook's [standard events](https://developers.facebook.com/docs/meta-pixel/reference#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](https://app.freshpaint.io/transformations/new) and select [Standard Event](https://app.freshpaint.io/transformations/new/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:
{% hint style="info" %} Some of Facebook's [standard events](https://developers.facebook.com/docs/meta-pixel/reference#standard-events) requires a certain set of properties. {% endhint %} 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](https://business.facebook.com/events_manager2/list) and navigate to the Overview tab and confirm the Purchase event is in the list:
{% hint style="info" %} Note: events may take a few minutes to populate in this view. {% endhint %} ## Options for Configuring Facebook Destinations There are a few different ways to implement conversion tracking with Freshpaint's Facebook integrations. You can use the [Facebook Conversions API ](/integrations/destinations/direct-response-ads/facebook-conversions-api.md)to complement tracking with your Facebook Pixel, or you can use the Pixel as a standalone integration. The option that's best for you depends on your specific goals with the Facebook Conversions API. You can choose from the following implementation options: 1. [Use only the Facebook Pixel](#use-only-facebook-pixel) 2. [Use both Pixel and Conversions API to send the same events](#use-both-pixel-and-conversions-api-to-send-different-events) 3. [Use both Pixel and Conversions API to send different events](#use-both-pixel-and-conversions-api-to-send-different-events) {% hint style="info" %} If you are a HIPAA customer, you should use only Facebook Conversions API {% endhint %} ### Use Only Facebook Pixel This approach is best if you are NOT a HIPAA customer and are not concerned about having granular control ever what data gets sent to Facebook. If you are a HIPAA customer, you should use the [Facebook Conversions API](/integrations/destinations/direct-response-ads/facebook-conversions-api.md) destination. #### Matching When you send user actions to Facebook, Facebook will attempt to match those actions to a particular Facebook user. The match rate can be improved by including [additional parameters](#additional-parameters). #### Deduplication In this approach, events are only sent from the browser, so no deduplication is necessary. ### Use both Pixel and Conversions API to send the same events By sending the same events from both the browser via the Pixel and the server via the Conversions API, you can improve the accuracy of browser events by providing redundancy. Events that previously would've been lost (e.g. due to the browser Pixel being blocked or network errors) can still be captured using the Conversions API. #### Matching When you send user actions to Facebook, Facebook will attempt to match those actions to a particular Facebook user. For matching in this configuration to work best, the same `external_id` should be sent from both the browser and server. This can be done by enabling the "Use User Id or Anonymous Id as External Id" setting in the Facebook Pixel destination. Enabling this setting will direct Freshpaint to use the User ID for identified users or Anonymous ID for anonymous users as Facebook's [`external_id`](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/external-id/) both on the browser for the Pixel and for the server/Conversions API, enabling Facebook to better match users. You can also improve the match rate by including some [additional parameters](#additional-parameters) to your events. #### Deduplication 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 from the Conversions API must arrive *after* the client event from the Pixel. In this case, the server event is discarded. {% hint style="warning" %} If the server events is received first, no deduplication occurs. The server event must arrive *after* the client event in order to deduplicate. {% endhint %} {% hint style="info" %} For Facebook to deduplicate events correctly, the recommended "Use UserId or Anonymous Id as External Id" setting must be enabled, OR the [`fbp` parameter ](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc)must be included in server-side events. {% endhint %} ### Use both Pixel and Conversions API to send different events In this configuration, you will send some browser events through the Pixel and some server events to the Conversions API. 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. #### Matching When you send user actions to Facebook, Facebook will attempt to match those actions to a particular Facebook user. For matching in this configuration to work best, the same `external_id` should be sent from both the browser and server. This can be done by enabling the "Use User Id or Anonymous Id as External Id" setting in the Facebook Pixel destination. Enabling this setting will direct Freshpaint to use the User ID for identified users or Anonymous ID for anonymous users as the[`external_id`](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/external-id/) both on the browser for the Pixel and for the server/Conversions API, enabling Facebook to better match users. You can also improve the match rate by including some [additional parameters](#additional-parameters) to your events. #### Deduplication In this approach, different events are sent from the browser and the server, so no deduplication is necessary. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.freshpaint.io/integrations/destinations/apps/facebook-pixel.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.