In this article, you’ll learn how to setup the Facebook’s new Conversions API.
We have included videos, sample scripts/code and a sample decision tree. Please import it into your LeadsHook account.
>>> Warning! Please Update the Pixel IDs from the Base Pixel AND Serverside API Call from the Sample Decision Tree Provided Below <<<
Assumptions
This guide will help you setup Facebook’s Conversation API. It is provided without our free support because setups vary from business to business and the steps required to complete these steps are for a technical audience.
UPDATE: 20 August 2021: Add a check so Facebook cookies are only saved AFTER cookies have dropped.
25th July 2021: Update saving of event ids into custom fields (please see video below)
10 July 2020 Update: The above decision tree has been updated with a new Webhook node for ViewContent serverside API call.
We have added updates to LeadsHook so a lot of complexity has been removed.
We do offer paid help if required or please post in the LeadsHook Users group for additional help from our amazing ‘technie’ users.
We’re assuming you already know or have your Facebook pixel setup.
Background
With the introduction of Apple’s new iOS updates (from v. 14.5+), there are severe limitations on tracking. One of these limitations is the length of time a cookie is kept alive. As a result conversion numbers are not correctly reported.
This ‘new’ conversions API from Facebook (in reality it’s not actually new). Conversions API has been provided for a few years. The iOS update has made it much more important for conversions.
Summary of Setup Process
- LeadsHook: Save browser information into custom fields
- LeadsHook: Save customer information into custom fields (part of decision tree).
- LeadsHook: Format data
- LeadsHook: Hash data
- LeadsHook: Update clientside events for deduplication
- Facebook: Setup FB Conversions API
- FaceBook: Build API URL, Insert API Token, API Version and Pixel ID
- LeadsHook: Send data to Facebook
- IF Embedding, Add function to YOUR website to pass cookie values to LeadsHook
What’s so Special About this Conversions API?
With the limitations on pixels, under certain circumstances, conversion data does not get back to Facebook. This conversions API reports the same conversions using an API. It’s also referred to as serverside API. Basically the conversion information is sent directly to facebook from a server and not from the browser.
The advantage is Apple can’t block serverside API communications because the message to Facebook is sent via a ‘back-channel’, i.e. an API call directly from LeadsHook servers to Facebook’s servers.
Any serverside Conversions API is much more robust solution.
Do I Still Need my FaceBook Pixel?
Short Answer: YES
Long Answer: You need to pass some information from Facebook so it knows which campaign, adset, ad (and a bunch of other info Facebook tracks) resulted in a conversion.
All the serverside API is doing is sending these details back to Facebook so it can match the conversion.
Dealing with Potentially Duplicate Conversions
Now, this creates a problem. Pixel based conversions are NOT dead (they’re just not as reliable).
What happens if the pixel sends a conversion AND the serverside API also sends a conversion. This will record 2 conversions which is obviously overstating your conversions. The technical term is called DEDUPLICATION. We’ll be going through this below in Step 7
Steps for Setting Up Your Facebook Conversions API
Please watch these 2 videos which explains the whole process…
Video which explains Event IDs & Event Time
Download the decision here: https://www.leadshook.com/help/wp-content/uploads/2021/08/facebook-conversions-api-v6-19-aug-2021_2021-08-19.zip
#0: Warning! Setup Can Be Difficult
Hopefully this article will reduce the time you spend on this setup.
As of May 2020, Facebook documents regarding serverside setup has some inconsistencies.
One of the inconsistencies is what their serverside API conversions tool says is required is different to what is explained in one of their more technical documents. One of the event parameters, “action_source” is not listed as a parameter in the conversions API conversions tool but is required in the pixel helper…
We have included this parameter in the sample setup (see below)
#1: Passing the Right Parameters to Facebook
The match rate of your conversion API calls is dictated by the quality of the params you need to send.
The data sent to Facebook has 4 different categories of parameters…
See the complete list of parameters here: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters
There are a minimum number of parameters needed for an event to be accepted.
For a better match, you can send more info especially about your customers and leads.
There are params you need to send that helps with deduplication.
This article will give examples using ‘ViewContent’ and ‘Lead’ events but you can use any other standard event as well. Please see the complete list of standard events and their required parameters here: https://developers.facebook.com/docs/facebook-pixel/reference#standard-events
Here is a comprehensive list of parameters you can pass, what they mean and where do you get them from. You’ll also see numbers/letter and associated scripts below. These scripts are designed to grab and save the data into various custom fields.
TIP! Please ensure you have setup custom fields for ALL of the variables you want to pass in your api call. And, ensure the you are correctly formatting the values of our parameters. E.g. Event time is a NUMBER is not wrapped in inverted commas ” “.
TIP! When you import the sample decision tree above your LeadsHook account will auotmatically create all of the fields that we have used in the sample decision tree. If you are using the SAME custom fields then you do not need to setup any additional custom fields.
LeadsHook automatically provides quite a few of the custom fields you need for your serverside setup. Please watch the video above for more details.
Here are list of custom fields you’ll need…
EVENT_TIME: Use _c_eventtime
EVENT_ID: Use _c_eventid
EVENT_SOURCE_URL: Use _c_eventurl
CLIENT_USER_AGENT: Use _c_useragent
CLIENT_IP_ADDRESS: Use ip_address
FBC COOKIE and FBCLID: Add fbclid custom field & Node Level Script
Note: Grab this from the cookie and fbclid from the url parameters. Since LeadsHook automatically grabs urls params as long as the custom field exists, create a custom field called ‘fbclid’.
Please create a new ANSWER text field called ‘fbclid’…
TIP! Also add the script provided under FBP COOKIE VALUE and save the _fbc cookie into its own custom field in addition to fbclid url param method shown below. Only 1 is needed for the conversion API.
FBC Cookie: Save cookie into using this LeadsHook function, DT.grabCookie(‘custom_field’,’cookie_variable’)
Add this to any node level script BEFORE your API call to Facebook using a Webhook Node. In our sample decision tree, we added it to the first node.
<script>
(function check_fbq () {
if (typeof fbq === 'undefined') setTimeout(check_fbq, 100)
DT.grabCookie('fbc', '_fbc')
console.log("fbc function fired [value: " + getCookie('_fbc') + "]")
})();
</script>
FBP COOKIE VALUE: Add Node Level Script
FBP Cookie: Save cookie into using this LeadsHook function, DT.grabCookie(‘custom_field’,’cookie_variable’)
Add this to any node level script BEFORE your API call to Facebook using a Webhook Node. In our sample decision tree, we added it to the first node.
<script>
(function check_fbq () {
if (typeof fbq === 'undefined') setTimeout(check_fbq, 100)
DT.grabCookie('fbp', '_fbp')
console.log("fbp function fired [value: " + getCookie('_fbp') + "]")
})();
</script>
#2 Formatting Parameter Values
Please ensure you are sending the parameters in the right format. When sending customer data, you need to use lowercase. This includes email addresses.
Above every text editor block inside LeadsHook, you’ll see find an easy way to find case filters list…
TIP! You can convert any custom field value using any of one of the 16 cases listed above. For the Facebook conversion api, add lowercase filter to all of your custom fields as follows…
{custom_field:lowercase}
{first_name:lowercase}
{email:lowercase}
The sample decision tree and code provided below contains more examples.
The complete list of Customer Information parameters and formatting requirements here: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
Phone Special Formatting Requirements
Phone numbers need to be formatted so they do not contain any spaces, brackets or any special characters like ‘+’.
Example: This phone in different formats:
- +1(415)963 9564
- 0011 1 415 963 9563
- +1415 963 9564
- 415-963-9563
- 415 963 9563
- (415) 963 9563
… needs be ‘cleaned’ so the final number is
14159639564
Transforming phone numbers into the correct format is really easy inside LeadsHook. You can use filters to transform the data.
Use the following filters to transform your phone number into the format required by Facebook
raw|international|no_leading_plus
Please note! You are not done yet – you still need to add HASH filter before Facebook will accept your API calls.
#3: How to Hash Your Customer Information Parameters Before Sending to Facebook
Hashing information inside LeadsHook is super easy. In fact we provide you with 5 different hash filters. Facebook requires customer information to be hashed using SHA256.
You can hash any custom field data for Facebook add the following filter…
sha256
TIP! Use can use this testing tool to confirm your hashed values: https://emn178.github.io/online-tools/sha256.html
Your final API call will contain custom fields with case filters, data formatting filters and hashing filters. Here are some examples…
Email hashed: {email|sha256}
Phone formatted & hashed: {phone_number|raw|international|no_leading_plus|sha256}
First name, lowercase & hashed: {first_name:lowercase|sha256}
Last name, lowercase & hashed: {last_name:lowercase|sha256}
#4: Facebook Pixel Setup & Check
This article will not go through basic of setting up a pixel. It’s assumed you already know how to do this.
You can turn on advanced matching as shown below. We’ll be using manual matching because it offers more flexibility and works in more usecases.
In case you’re working in a regulated vertical then you don’t be able to do this. You can still manually set this up as you’ll see in Step 4.
Use manual Advanced Matching if your business is in a regulated vertical: We don’t allow businesses in regulated verticals to use Automatic Advanced Matching.
https://www.facebook.com/business/help/930861050579797
#5: Facebook Conversions API Setup
Serverside URL Format:
https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}
Here’s how to get the values for API_VERSION, PIXEL_ID and TOKEN…
Your after you add in the values of the variables from your account, it should look something like this…
https://graph.facebook.com/v10.0/12345679891234567/events?access_token=ecewocon38dy82dh423h2444f44wcehwche48c843
#6: Deduplication Setup
Deduplication is just a fancy way to saying if you’re sending data via the pixel, i.e. the clientside events like ViewContent, Lead AND also sending this same information via the serverside API then you are sending duplicate conversion data.
Facebook has provided a way to remove any duplicated and its quite easy because we have already done the work above. 🙂
Video on De-duplicates…
METHOD 1 (Recommended by Facebook)
Send event name and event id.
METHOD 2
Send event name, fbp pixel value, and/or an external id.
We already have the event name and fbp pixel value. For external ID, we recommend you use LeadsHook, lead_id because it’s easy and does the job. But you are free to use any other id as well. All you need to do is hash it before sending it to Facebook.
We recommend sending all: Event name, event id, fbp pixel and an external id. Marked below in yellow on the left hand side under “Serverside Conversions”).
You need to make one final small adjustment to your clientside events. Marked below in yellow on the right hand side under “Clientside Conversions.
IMPORTANT! Please be sure to use the same event id value for both of your serverside and clientside events as shown below.
NOTE: For Deduping your external Thank you Page events like Lead. You will need to pass event ID via the exit URL parameter as shown below. Take note, it should be the same exact Event ID with the event you are trying to deduplicate.
const queryString = window.location.search;
const urlParams = new URLSearchParams(queryString);
const eventID = urlParams.get('eventID')
console.log(eventID);
You will also need to add the code above to your page, so it will grab the URL parameter being passed so the pixel code can use the value and send to Facebook. You can add it before the pixel.
You can then edit the fbq function for the event that you are trying to dedupe and add the event ID value.
Example for updating the fbq Lead function:
You can refer more here:
https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events/
#7: Testing & Confirm Setup
Download Sample Decision Tree from above
- Grab the test param from your pixel…
2. Update your payload with the ‘test_event_code’ parameter as shown below.
3) Add a Webhook Node For Your Lead Event
You can also add view content events
4) Setup your webhook as follows…
Sample Payload to add to your Webhooks Node.
TIP! Please adjust as needed. We left in some hashed values for testing. E.g Gender (ge): for testing. For your payload, you MUST add a custom field like {fb_gender:lowercase|sha256}. The values below need to be updated with your custom fields. The hashed values below are there for a quick test only.
{
"data": [
{
"event_name": "Lead",
"event_time": {_c_eventtime},
"action_source": "website",
"event_id": "{_c_eventid}",
"event_source_url": "{_c_eventurl}",
"user_data": {
"client_user_agent": "{_c_useragent}",
"client_ip_address": "{ip_address}",
"fbc": "{fbc}",
"fbp": "{fbp}",
"em": "{email|sha256}",
"ph": "{phone_number|raw|international|no_leading_plus|sha256}",
"fn": "{first_name:lowercase|sha256}",
"ln": "{last_name:lowercase|sha256}",
"db": "531764f38242ecae4d34116402255481859cf83552a545cad2b03268a4204f1a",
"ge": "62c66a7a5dd70c3146618063c344e531e6d4b59e379808443ce962b3abd63c5a",
"ct": "6d5809aba9e26ace73438fc81a5d012738b61a5b6fc913d5100e449e72d80ee2",
"st": "4b650e5c4785025dee7bd65e3c5c527356717d7a1c0bfef5b4ada8ca1e9cbe17",
"zp": "b83c588da0c6931625f42e0948054a3ade722bfd02c27816305742ed7390ac6c",
"country": "9b202ecbc6d45c6d8901d989a918878397a3eb9d00e8f48022fc051b19d21a1d",
"external_id": "{lead_id|sha256}"
},
"custom_data": {
"currency": "USD",
"value": "142.52",
"content_name": "Content Name",
"content_category": "Content Category",
"content_ids": ["Content ID"]
}
}
],
"test_event_code": "TEST34465"
}
#8 Troubleshooting Errors
Short video on how to troubleshoot issues
#9 When Embedding, Add function to YOUR website to pass cookie values to LeadsHook
Here are instructions on grabbing cookie values when embedding your decision tree
When embedding a LeadsHook decision tree into another website, any cookies are dropped in the 3rd party context.
This will allow you to pass data to LeadsHook directly from your Website!
IOS & Browser Updates are no longer allowing 3rd party cookies. This is where a cookie is placed by a website whose url is NOT the website you’re on.
E.g. When you add a Facebook pixel to your website and your decision tree, your website will place cookie in a first party context (technically the context is first party, not the cookie — but the accepted term is 1st party cookie).
When the FB pixel fires inside LH, it will also try to place a cookie but because your-account.leadshook.io is a 3rd party with respect your website, the cookie now will be fired in a 3rd party context, i.e. 3rd party cookie).
3rd party cookies are now blocked…
This means the pixel fires but no cookies are added when your LeadsHook decision tree is embedded.
And, your serverside tracking is affected.
For completeness, direct link decision trees are not affected since it’s first party.
For this reason we will be adding the ability for you to pass data such as tracking ids like subids AND cookies from your website directly into LeadsHook custom fields for use in serverside API calls for FB (and for all other purposes).
See instructions here: