Facebook Conversions API

Overview

Facebook Conversions API is a tool that provides a way for businesses to track important events on their website or applications through a single endpoint rather than across multiple sources. The events can be purchases, form submissions and page views, which they can then send directly to Facebook. This information can then be used to optimise ad campaigns and measure their effectiveness, as well as provide insights into how people are interacting with a business’s website or applications. The below image illustrates how the Conversions API works in conjunction with Facebook Pixel.

Note:Facebook recommends you use a setup with both the Facebook Pixel and the Conversions API to pass the events. However, Zeotap only offers implementation for the server-to-server Conversions API. Therefore, the responsibility to implement the Pixel lies with you.

Why use this Integration?

Integrating with the Facebook Conversions API offers several significant advantages, including:

Extended Conversion Insights: Utilising the API, you can base your decisions on a broader range of information, including CRM data and conversion paths across multiple sites within a website or application.
Data Control: The Conversions API gives you added control over what data you share.
Reliability and Resilience: The Conversions API is intended to be more resilient to problems such as connectivity issues or browser crashes. As new industry regulations impose restrictions on data transmission, cookies and pixel tracking may become less effective and the Conversions API provides a means of controlling the sharing of signals that may no longer be captured by the pixel.

Process Overview

The following are the high-level steps for setting up the Conversions API integration:

Choose the integration method that is right for you. For example, Web, App and so on.
Complete the necessary prerequisites for the implementation you choose.
Implement and verify your setup.

Choose your Integration Approach

Before you proceed with this Integration, ensure to choose a suitable approach that fits your business requirement, based on the following actions:

Define the events and attributes to send to Conversions API
Choose a deduplication strategy

Define the Events to Send

After you have decided on the use case for your integration, specify the events and parameters that you want to send to Facebook. You can choose this in the Actions and Mapping screen while creating the Destination. Note that you can send events attributes, user data, app data and custom data to Conversions API.

Choose a Deduplication Strategy

Advertisers do not want to send the same event twice through the Conversions API and the Facebook Pixel as it results in the duplication of events. Hence, deduplication is necessary. We recommend an approach that enables the deduplication of events sent through the Facebook Pixel on the web and the Conversions API. Our recommended approach is that you must ensure both events (Pixel and Conversions API) use the identical Event Name. Also, ensure that either Event Id or a combination of External Id and FBP is included. We recommend you include all these parameters to help Facebook properly deduplicate events and reduce double reporting of identical events. Based on the combination of parameters that you choose, ensure that you ingest the respective attributes to Zeotap and map them within Zeotap CDP. For more information about the Deduplication Strategy, refer here.

Components of the Conversions API

Ensure that you have the following details available before creating a destination for Conversions API:

Dataset ID/Pixel ID - Different approaches for Website and App events
Access Token
Business Manager

Dataset ID/Pixel ID (Applicable for Website events)

A pixel is a tool that allows you to track your website visitors’ activities. You can perform the following steps to get your Dataset ID/Pixel ID from Facebook Events Manager.

Log into Facebook Events Manager.

On the left navigation bar, select Business Tools, and then click Events Manager.

Under Data Sources, Open the Pixel that you created and find the Dataset ID as shown below.

Linking the App to the Dataset ID (Applicable for App events)

Once you create an App in the Developer’s page, the app gets listed in Facebook Events manager under the Data sources tab as shown below.

You can identify the App that you created by the App name and the Phone symbol beside it. To link your App to the Dataset ID, perform the following steps in the Events Manager:

Navigate to the Data Sources tab.

Locate your app’s Setting tab.

Perform the linking process.

Note that once you complete the linking, the dataset includes the connected App.

Access Token

Perform the following steps to generate an access token:

Log into Facebook Events Manager.

Choose the relevant Facebook Pixel and click the Settings tab.

In the Conversions API section, click Generate access token under the Set up manually section, as shown in the image below.

Note:The generate access token link is visible only to the users with developer privileges for the business. The link is hidden for other users.

Business Manager

Note that you need to have a Business Manager to use the Conversions API. This helps advertisers integrate Facebook marketing efforts across your business and partners. For more information on how to create a Business Manager account, refer to the article how to Create a Business Manager.

Destination Setup

After you have applied filters or added conditions for your users in Journeys, you can activate them in Facebook Conversions API under Send to Destinations. A new window appears, where you can set up your destination. You can use an already existing destination from the list of available Destinations **** or create a new one by clicking + Add New Destination.

Add New Destination

Perform the following steps to add a new destination:

Click Add New Destination.

Search for Facebook Conversions API.

Click Facebook Conversions API and enter a name for the Destination.

Add the Pixel ID and Access Token that you have obtained as explained above.

Click Next to proceed to the Actions and Mapping screen.

In the mapping screen that appears, under Choose your Action, you can either choose Stream events to Facebook Conversions API or Send offline data to FB Enhanced CAPIas the action based o your use case for sending data from the workflow created in Journeys.a. If you choose Stream events to Facebook Conversions API as the action, then, under Map the Fields, certain fields like Email, Phone, First Name, Last Name and so on, which are relevant to Conversions API auto populates. You can map the Zeotap Catalogue fields to the appropriate Conversions API fields (Destination fields).If the suggested object properties do not suit your requirements, then you can add custom data that can then be mapped to the relevant Zeotap field and sent to Facebook. Note that Custom properties can be used with both standard and custom events. For more information about Standard and Custom events, refer here.

Once the mapping is complete, click Create Destination. The destination is created and made available for activation on Journeys, which you can be used send the events and parameters (customer, server and custom parameters) to the Conversions API. Note that you must map the following mandatory fields to establish a working connection with Facebook Conversions API.

Parameter	Type
Event Source URL	Server event
Client User Agent	Customer information

Activate the Destination on Journeys

After creating a destination, next, you need to link it in the Send to Destination node within the workflow, as explained below.

In the workflow, click + and choose Send to Destinations.

Choose the destination from the list of available destinations by using the search feature.

Under the Destination Details tab, the Pixel ID and Access Token fields are automatically populated based on the value that you have entered while creating the destination.a. Under Action Source, choose either app or website based on your requirement.i. App events allows you to track actions that occur in your mobile app or web page such as app installs and purchase events. By tracking these events you can measure ad performance and build audiences for ad targeting. The following are the three types of App Events:

Automatically Logged Events - The Facebook SDK can automatically log app installs, app sessions, and in-app purchases
Standard Events - Popular events that Facebook has created for you
Custom Events - Events you create that are specific to your app

ii. Website events allows you to track conversions (for example, purchases, sign-ups and more) that occur within a browser window after a user clicks on an ad or lands on a Facebook-hosted page. With this API, you can receive insights into the effectiveness of your Facebook ads and make data-driven decisions to optimize your campaigns.b. Under Event Name, choose the desired event using the drop-down menu.

Under the Destination Settings tab, choose the Action and mapping as per your requirement.

Upon clicking Save Destination. The destination is attached as shown in the image below.

Standard Event Names

You can include the following predefined object properties with any standard event or custom event that support them:

Event Name	Description	Object Properties
AddPaymentInfo	This indicates that payment information is added in the checkout flow.	Optional Properties -Content Category, Content Ids, Currency, Value
AddToCart	This indicates that a product is added to the shopping cart.	Optional Properties -Content Ids, Content Name, Currency, Value
AddToWishlist	This indicates that a product is added to a wish list.	Optional Properties -Content Name, Content Category, Content Ids, Currency, Value
CompleteRegistration	This indicates that a registration form is completed.	Optional Properties -Content Name, Currency, Status, Value
Contact	This indicates that a person has initiated contact with your business through telephone, SMS, email, chat and so on.
CustomizeProduct	This indicates that a person has customised a product.
Donate	This indicates that a person has donated funds to your organisation or cause.
FindLocation	This indicates that a person searches for a location of your store through a website or app, with the intention to visit the physical location.
InitiateCheckout	This indicates that a person has initiated the checkout flow.	Optional Properties -Content Category, Content Ids, Currency, Num Items, Value
Lead	This indicates that a sign-up is completed.	Optional Properties -Content Category, Content Name, Currency, Value
Purchase	This indicates that a purchase is made or the This indicates that checkout flow is completed.	Mandatory Properties -Currency, ValueOptional Properties -Content Ids, Content Name, Num Items
Schedule	This indicates that a person has booked an appointment to visit one of your locations.
Search	This indicates that a search is made.	Optional Properties -Content Category, Content Ids, Currency, Search String, Value
StartTrial	This indicates that a person has started a free trial of a product or service you offer.	Optional Properties -Currency, Predicted ltv, Value
SubmitApplication	This indicates that a person has applied for a product, service or program you offer.
Subscribe	This indicates that a person has applied to start a paid subscription for a product or service you offer.	Optional Properties -Currency, Predicted ltv, Value
ViewContent	This indicates that a person has visited the web page you care about (for example, a product page or landing page). Note that ViewContent informs you if someone visits a web page’s URL, but not what they see or do on that page.	Optional Properties -Content Ids, Content Category, Content Name, Currency, Value

Event Parameters

The event parameters include all the necessary event data parameters along with other data parameters that the Conversions API requires to optimise ads delivery and attribution.

Customer Parameters

Note that sending additional customer information parameters may increase the Event Match Quality. The events that are matched can exclusively be utilised for ad delivery optimisation and attribution. However, unmatched events cannot be utilised for attribution or ad delivery optimisation but can still be used for fundamental measurement. The following are examples of high-quality customer information parameters :

email address (em)
IP address (Client IP Address)
name (fn and ln)
phone number (ph)

The table below lists the supported customer parameters.

Customer Information Parameter	Description
Email	• This indicates the email address of the user. • Example: [email protected]
Phone Number	• This indicates the phone number of the user. • Example: 15557893473
First Name	• This indicates the first name of the user. • Example: john
Last Name	• This indicates the last name of the user. • Example: paul
Date of Birth	Ensure that Date of Birth is ingested to Zeotap in the format of YYYYMMDD. • Example: 19911112 for November 12, 1991
Gender	• This indicates the gender of the user in the form of an initial. • Options are: • f for female, • m for male
City	• This indicates the city without space or punctuation. • Example: Paris
State	• This indicates the US State abbreviations. • Example: az
Zip Code	• This indicates the Zip code with no spaces and dash. • Only the first 5 digits of US zip codes are considered. • Use the area, district and sector format for the UK. • Example: • U.S zip code: 94035, • Australia zip code: 1987, • France zip code: 75018, • UK zip code: m11ae
Country	• This indicates the two-letter country code. • Example: us
External ID	• This indicates any unique ID from the advertiser, such as loyalty membership IDs, user IDs and external cookie IDs. • If an External ID is sent through other channels, then it must be in the same format as sent through the Conversions API. If you are sending a hashed External ID in the pixel, then ensure that it is ingested into Zeotap as well.
Client IP Address	• The IP address of the browser corresponding to the event must be a valid IPV4 or IPV6 address. IPV6 is preferable over IPV4 for IPV6-enabled users. • The Client IP Address user data parameter must never be hashed. • No spaces must be included. • Always provide the real IP address to ensure accurate event reporting. • Example: • IPV4: 168.212.226.204, • IPV6: 2001:0db8:85a3:0000:0000:8a2e:0370:7334
Client User Agent	• This indicates the user agent for the browser corresponding to the event. The Client User Agent is required for website events shared using the Conversions API. • Example: • Mozilla/5.0 (Windows NT 10.0; Win64; x64) • AppleWebKit/537.36 (KHTML, like Gecko) • Chrome/87.0.4280.141 • Safari/537.36
Click ID	• Value is stored in the _fbc browser cookie under your domain. • The format is `fb.${subdomain_index}.${creation_time}.${fbclid}`. • Example: fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 Ensure that the Click ID is ingested into Zeotap.
Browser ID	• Value is stored in the _fbp browser cookie under your domain. • The format is `fb.${subdomain_index}.${creation_time}.${random_number}`. • Example: fb.1.1596403881668.1116446470 Ensure that the Browser ID is ingested into Zeotap.

Server Event Parameters

These parameters consist of all the required server data parameters that the Conversions API uses for ads attribution and/or ads delivery optimisation.

Event Name	Type	Description	Required
Event Time	integer	This is a Unix timestamp in seconds indicating when the actual event occurred.
Event Source URL	string	This is the browser URL where the event happened. The URL must begin with http:// or https:// and must match the verified domain.The Event Source URL is required for website events shared using the Conversions API.	Mandatory
Opt Out	boolean	This is a flag that indicates that you must not use this event for ads delivery optimisation.	Optional
Event Id	string	This ID can be any unique string chosen by the advertiser.The Event Id and Event Name parameters are used to deduplicate events sent by both web (through the Facebook Pixel) and the Conversions API. Note that while Event Id is marked optional, it is recommended for event deduplication.	Optional
Action Source	string	Zeotap sends the website as the action source, enabling tracking of conversions made on your website.

Custom Data Parameters

This table lists the parameters to send additional data for ads delivery optimisation.

Parameter	Description
Content Category	This indicates the category of the content associated with the event. Example: ‘grocery’
Content Ids	This indicates the content IDs associated with the event, such as product SKUs for items in an AddToCart event.Example: [‘ABC123’]Note: As Zeotap does not support lists, we send a single object array to Facebook.
Content Name	This indicates the name of the page or product associated with the event.Example: ‘lettuce’
Currency	This parameter is required for purchase events.This indicates the currency for the value specified, if applicable. Currency must be a valid ISO 4217 three-digit currency code.Example: ‘USD’
Num Items	Use only with InitiateCheckout events. This indicates the number of items that a user tries to buy during checkout.Example: ‘4’
Order Id	This indicates the order ID for this transaction as a string.Example: ‘order1234’
Predicted ltv	This indicates the predicted lifetime value of a conversion event.Example: 432.12
Search String	Use only with Search events. This indicates a search query made by a user.Example: ‘lettuce’
Satus	Use only with CompleteRegistration events. This indicates the status of the registration event as a string.Example: ‘registered’
Value	This parameter is required for purchase events. This indicates a numeric value associated with this event and can be a monetary value or a value in some other metric.Example: 142.54

Verify the Setup

For information about how to verify your setup, refer here.

Best Practice

One of the best practices for integrating with the Conversions API is outlined below:

Understanding Baseline Requirements for Matching

An event is considered invalid if it only includes customer information parameters that consist of one of the following combinations, (or a subset thereof):

ct + country + st + zp + ge + client_user_agent
db + client_user_agent
fn + ge
ln + ge

For example, consider an event with only the customer information parameters ge, ct, st and country (this can correspond to a man, in Menlo Park, California, USA). This event gets rejected as the customer information parameters are a subset of one of the above combinations.

​Overview

​Why use this Integration?

​Process Overview

​Choose your Integration Approach

​Define the Events to Send

​Choose a Deduplication Strategy

​Components of the Conversions API

​Dataset ID/Pixel ID (Applicable for Website events)

​Linking the App to the Dataset ID (Applicable for App events)

​Access Token

​Business Manager

​Destination Setup

​Add New Destination

​Activate the Destination on Journeys

​Standard Event Names

​Event Parameters

​Customer Parameters

​Server Event Parameters

​Custom Data Parameters

​Verify the Setup

​Best Practice

​Understanding Baseline Requirements for Matching

Overview

Why use this Integration?

Process Overview

Choose your Integration Approach

Define the Events to Send

Choose a Deduplication Strategy

Components of the Conversions API

Dataset ID/Pixel ID (Applicable for Website events)

Linking the App to the Dataset ID (Applicable for App events)

Access Token

Business Manager

Destination Setup

Add New Destination

Activate the Destination on Journeys

Standard Event Names

Event Parameters

Customer Parameters

Server Event Parameters

Custom Data Parameters

Verify the Setup

Best Practice

Understanding Baseline Requirements for Matching