Meta Conversions API
Load the Facebook Conversions API tag template from the template gallery.
Go to ‘templates’ in the server container and click on the ‘Tag Templates’ box. Here you can click on the ‘Search Gallery’ button.
Search for the ‘Facebook Conversions API Tag’ template, and click on ‘Add to workspace’ when you find it.
In the server container, go to ‘Tags’ and create a new tag. Choose the ‘Facebook Conversions API Tag’ template as the tag configuration.
To send data to the Conversions API, you will need the following information:
The pixel ID to which the data will be sent
An API access token for interacting with the Conversions API
A test event code (test_event_code) that allows the Conversions API to be tested without actually collecting data on the pixel. This is optional.
You can also set the ‘Action Source’ here if desired.
Finally, you want the tag to be triggered when the GA4 client is activated.
The easiest way to work with the Facebook tag is to trigger it when a GA4 request is processed by the GA4 client. You need to create a custom trigger for this, where the condition is that ‘Client Name’ equals. When you create a GA4 client with the name ‘GA4’, the trigger will look like this:
When you add this trigger to the Facebook tag, it will attempt to send the data to Facebook whenever a GA4 event is processed.
It is possible that you want the tag to be triggered only when specific GA4 requests are received. You may want to trigger the tag only when it contains a Facebook parameter or when it has a certain event name.
The above trigger will only be activated when the GA4 client receives a request and when the query string of the request contains a query parameter that starts with ‘ep.x-fb-’ or ‘epn.x-fb-’.
‘Query String’ is a built-in variable that can be enabled in the ‘Variables’ section of the server container.
The above ‘Lookup Table’ can be used to set the tag in such a way that it is only triggered for a specific set of event names. In the trigger of the Facebook tag, add the condition that this ‘Lookup Table’ must be converted to the ‘true’ value to activate the tag.
Keep in mind that the event names must match the names set in the GA4 web tag. So when you have a ‘page_view’ GA4 web event that should trigger the Facebook tag, you must add ‘page_view’ to your list of allowed events.
Put both the server container and the web container in preview mode and perform an action that triggers a GA4 event, which is designed for Facebook data collection, in the web container.
In the preview mode of the web container, you should see a GA4 request to the server container. To see this, make sure you have selected the ‘GA4 Measurement ID’ in the preview filters instead of the GTM container ID.
In the preview mode of the server container, you should see an incoming HTTP request. The event name you configured in the GA4 web tag should be displayed under the request.
When you select the request, you should see an outgoing request to Facebook (and possibly also to GA4).
When you select the Facebook request, you should see the correct access token in the URL, the formed request body with all the parameters you included, and a ‘200’ status code indicating a successful request.
Also, check the outgoing request to GA4 to ensure that all the parameters you wanted to exclude are indeed excluded.
Finally, you should see your event coming in on Facebook in the Test Events tool (assuming you used the ‘test_event_code’ parameter).
If it doesn’t work, check for possible error responses from Facebook by opening the request details in the preview mode of the server container.
The GA4 tags executed in the web browser collect events in the usual way as they have done so far. But instead of sending these events directly to the Google Analytics servers, you will configure the “transport_url” field in the GA4 Config tag. This ensures that the requests are sent to your own server container. If this has not yet been done, you should first follow the steps for setting up the Google Analytics 4 connection.
Additionally, new fields will need to be added to the GA4 requests so that the Facebook tag template can access this information. This includes information such as ‘User Data’ parameters and certain ‘Facebook custom data parameters’ that you want the server-side tag to collect as well.
######Updating the GA4 web tag
If you are just starting to work with server containers, it is advisable to copy the existing GA4 web tags instead of replacing the functionalities with the “transport_url”. This way, you can ‘parallel track’ via the web tag and the server container. You may want to create a new data stream within GA4 specifically for your server-side hits.
There is an ‘Event Name’ field present within the GA4 web tag. You can fill this in however you want and it will work with Facebook. However, there are some event names that have special functionalities and are automatically converted to the standard event name format of Facebook.
Here is the list of event names:
When you use one of the names in the left column as the GA4 ‘Event Name’, Facebook will convert it to the corresponding values from the right column when collecting the data. Any other event names are used as they are entered, without changes from Facebook when collecting the data.
There are a number of ‘utility’ parameters that you can set as GA4 event parameters, and these are treated specially by the Facebook tag.
event_time
The ‘event_time’ parameter should only be set when the data is collected on the website. The format is ‘UNIX (epoch) time’ in seconds. In other words, to get the current timestamp with a custom JavaScript variable, this can be used:
```plain
function() {
return Math.round(new Date().getTime() / 1000);
}
This does not need to be actively sent. If it is not part of the GA4 hit, the Facebook tag will simply set the timestamp to when the server-side tag was executed.
event_id
‘event_id’ is used to deduplicate identical events collected from more than one source (e.g., the website & the server container). This is only relevant when duplicating data collection between the web pixel and the server container. If you are collecting events with only one of the two, you do not need to use ‘event_id’.
The event id must be unique for all events that need to be deduplicated. Each set of events that need to be deduplicated must have its own unique event id. Otherwise, Facebook cannot consistently deduplicate the data.
Deduplication is a technique for removing duplicate copies of repeating data.
With Google Tag Manager, it is relatively difficult to create a consistently unique event id. For example, when using the variable {{Random Number}} as the event id in a web pixel and server-side, it will return a different variable in both cases when called.
An easy way to create the event id is to generate a random page id for each page load and then concatenate it with a sequence number that increments by one for each set of Facebook events that need to be deduplicated. Another way is to push an event with a random and unique event id to the ‘dataLayer’ for each set of Facebook tags that need to be deduplicated. This way, the Facebook hits (that require deduplication) can be triggered on the event and use the event id in the pushed object.
page_location
‘page_location’ is automatically fetched from the URL of the page, but it can still be overwritten with a custom value as in the above screenshot. This is then collected as ‘event_source_url’ by the Facebook tag on the server side.
action_source
The ‘action_source’ can be set to the following:
email
website
app
phone_call
chat
physical_store
system_generated
other
This field is optional and specifies the context of the hit, i.e., where the conversion took place.
You can also configure the action source in the Facebook tag on the server side. When you send the ‘action_source’, it overrides the tag setting on the server side.
With the proper consent and/or other controlled legal bases, you can also send user data parameters to Facebook to match the conversion with the user who performed the action.
Make sure you have the legal right to send end-user personal data to Facebook. Do not follow the instructions below blindly - ensure that you do not violate users’ privacy rights.
To ensure that user data parameters work in the server-side settings, the following field must be added to the event parameters of the GA4 tag that sends the user data:
Set the field name to ‘first_party_collection’ and the value to ‘true’.
If you wish, you can override the IP address and User-Agent sent to Facebook using the GA4 web tag. This is a good way to anonymize the request if you do not want Facebook to use the user’s IP address and User-Agent.
o override the IP address, the ‘ip_override’ field must be set. To override the User-Agent, the ‘user_agent’ field must be set. If you do not override these fields, the server-side tag will send the user’s actual IP address and User-Agent to Facebook to assist with user matching.
You can also explicitly send personal data about users to Facebook. The server-side tag obfuscates the data, so Facebook never receives the data in a readable format.
If the data is already obfuscated when sent with the GA4 tag, the Facebook tag will not obfuscate it again.
These are the parameters for which this can be set:
user_data.email_adress
user_data.phone_number
user_data.address.first_name
user_data.address.last_name
user_data.address.city
user_data.address.region
user_data.address.postal_code
user_data.address.country
This is how it would look in the GA4 web tag:
There are also a number of Facebook-specific parameters that can be set. These are not automatically obfuscated.
You can send the ‘_fbp’ and ‘_fbc’ cookie values using the parameters mentioned above. If you do not explicitly set these, and the user has those cookies in their browser, and the server-side tagging endpoint is first-party, then the Facebook tag will automatically read the cookie values from the user’s cookies.
This is how some of these parameters would look in the GA4 event tag:
Custom data parameters can also be sent to Facebook by setting them as fields in the GA4 web tag.
There are a number of general parameters that can be set in the GA4 web tag. The server-side tag of Facebook can read these and send them to Facebook.
This is how these parameters look in the GA4 event tag:
If you collect e-commerce data on GA4, you might already have an ‘items’ array. The Facebook tag can automatically take over the contents of this ‘items’ array on the server side and turn it into a ‘contents’ array.
This is how the mapping is done:
This is by far the easiest way to build the ‘contents’ array. You can also send the ‘contents’ array as a custom parameter called ‘x-fb-cd-contents’.
You can also send a number of custom data parameters specific to Facebook. These are:
Here is an example of how these parameters look in the GA4 events tag:
When testing the Conversions API endpoint, you can use the ‘test_event_code’ parameter to collect hits on your Facebook account, including additional debugging information.
You can also set the ‘test_event_code’ parameter in the GA4 web tag. All you need to do is set the parameter as follows:
However, it might be easier to configure the ‘test_event_code’ parameter in the Facebook tag on the server side.
When the ‘transport_url’ field of the GA4 web tag is set to point to your server-side endpoint, the endpoint receives a GA4 request when such a tag is triggered on the website.
If the server-side endpoint does not have a GA4 client configured, the request will fail with a ‘400’ error.
This should be sufficient to allow the server-side endpoint to claim incoming GA4 requests and process them in the format required for the Facebook tag.
Because you are adding new parameters to the GA4 web tag, you may not want to send them to GA4 right away. This is especially true for all preset ‘x-fb-’ parameters.
The GA4 tag on the server side does not send user data parameters (the parameters that start with ‘user_data’). So if you send a non-obfuscated email address as the ‘user_data.email_address’ parameter to your server container, it will not be processed by the GA4 tag on the server side.
But for all other parameters, you should add the parameters you want to exclude to the respective setting of your GA4 tag(s) on the server side.
As an example, you can see in the screenshot below that the ‘x-fb-cd-ge’ (for gender), ‘x-fb-cd-db’ (for date of birth), and ‘x-fb-cd-content_type’ (for content type) are not sent to GA4:
The best way to get a list of parameters processed by the GA4 client is to view the preview mode of the server container, especially the ‘Event Data’ tab for all events that trigger a GA4 tag.
Above, you can see how the three ‘x-fb-…’ parameters were generated by the GA4 client, so they need to be added to the exclusion list in the GA4 tag on the server side.
Go to ‘templates’ in the server container and click on the ‘Tag Templates’ box. Here you can click on the ‘Search Gallery’ button.
Search for the ‘Facebook Conversions API Tag’ template, and click on ‘Add to workspace’ when you find it.
In the server container, go to ‘Tags’ and create a new tag. Choose the ‘Facebook Conversions API Tag’ template as the tag configuration.
To send data to the Conversions API, you will need the following information:
The pixel ID to which the data will be sent
An API access token for interacting with the Conversions API
A test event code (test_event_code) that allows the Conversions API to be tested without actually collecting data on the pixel. This is optional.
You can also set the ‘Action Source’ here if desired.
Finally, you want the tag to be triggered when the GA4 client is activated.
The easiest way to work with the Facebook tag is to trigger it when a GA4 request is processed by the GA4 client. You need to create a custom trigger for this, where the condition is that ‘Client Name’ equals. When you create a GA4 client with the name ‘GA4’, the trigger will look like this:
When you add this trigger to the Facebook tag, it will attempt to send the data to Facebook whenever a GA4 event is processed.
Conditional triggering (optional)
It is possible that you want the tag to be triggered only when specific GA4 requests are received. You may want to trigger the tag only when it contains a Facebook parameter or when it has a certain event name.
The above trigger will only be activated when the GA4 client receives a request and when the query string of the request contains a query parameter that starts with ‘ep.x-fb-’ or ‘epn.x-fb-’.
‘Query String’ is a built-in variable that can be enabled in the ‘Variables’ section of the server container.
The above ‘Lookup Table’ can be used to set the tag in such a way that it is only triggered for a specific set of event names. In the trigger of the Facebook tag, add the condition that this ‘Lookup Table’ must be converted to the ‘true’ value to activate the tag.
Keep in mind that the event names must match the names set in the GA4 web tag. So when you have a ‘page_view’ GA4 web event that should trigger the Facebook tag, you must add ‘page_view’ to your list of allowed events.
Testing your setup
Put both the server container and the web container in preview mode and perform an action that triggers a GA4 event, which is designed for Facebook data collection, in the web container.
In the preview mode of the web container, you should see a GA4 request to the server container. To see this, make sure you have selected the ‘GA4 Measurement ID’ in the preview filters instead of the GTM container ID.
In the preview mode of the server container, you should see an incoming HTTP request. The event name you configured in the GA4 web tag should be displayed under the request.
When you select the request, you should see an outgoing request to Facebook (and possibly also to GA4).
When you select the Facebook request, you should see the correct access token in the URL, the formed request body with all the parameters you included, and a ‘200’ status code indicating a successful request.
Also, check the outgoing request to GA4 to ensure that all the parameters you wanted to exclude are indeed excluded.
Finally, you should see your event coming in on Facebook in the Test Events tool (assuming you used the ‘test_event_code’ parameter).
If it doesn’t work, check for possible error responses from Facebook by opening the request details in the preview mode of the server container.
Extra information
The GA4 web tag logs the event
The GA4 tags executed in the web browser collect events in the usual way as they have done so far. But instead of sending these events directly to the Google Analytics servers, you will configure the “transport_url” field in the GA4 Config tag. This ensures that the requests are sent to your own server container. If this has not yet been done, you should first follow the steps for setting up the Google Analytics 4 connection.
Additionally, new fields will need to be added to the GA4 requests so that the Facebook tag template can access this information. This includes information such as ‘User Data’ parameters and certain ‘Facebook custom data parameters’ that you want the server-side tag to collect as well.
######Updating the GA4 web tag
If you are just starting to work with server containers, it is advisable to copy the existing GA4 web tags instead of replacing the functionalities with the “transport_url”. This way, you can ‘parallel track’ via the web tag and the server container. You may want to create a new data stream within GA4 specifically for your server-side hits.
Event name
There is an ‘Event Name’ field present within the GA4 web tag. You can fill this in however you want and it will work with Facebook. However, there are some event names that have special functionalities and are automatically converted to the standard event name format of Facebook.
Here is the list of event names:
When you use one of the names in the left column as the GA4 ‘Event Name’, Facebook will convert it to the corresponding values from the right column when collecting the data. Any other event names are used as they are entered, without changes from Facebook when collecting the data.
General parameters
There are a number of ‘utility’ parameters that you can set as GA4 event parameters, and these are treated specially by the Facebook tag.
event_time
The ‘event_time’ parameter should only be set when the data is collected on the website. The format is ‘UNIX (epoch) time’ in seconds. In other words, to get the current timestamp with a custom JavaScript variable, this can be used:
```plain
function() {
return Math.round(new Date().getTime() / 1000);
}
This does not need to be actively sent. If it is not part of the GA4 hit, the Facebook tag will simply set the timestamp to when the server-side tag was executed.
event_id
‘event_id’ is used to deduplicate identical events collected from more than one source (e.g., the website & the server container). This is only relevant when duplicating data collection between the web pixel and the server container. If you are collecting events with only one of the two, you do not need to use ‘event_id’.
The event id must be unique for all events that need to be deduplicated. Each set of events that need to be deduplicated must have its own unique event id. Otherwise, Facebook cannot consistently deduplicate the data.
Deduplication is a technique for removing duplicate copies of repeating data.
With Google Tag Manager, it is relatively difficult to create a consistently unique event id. For example, when using the variable {{Random Number}} as the event id in a web pixel and server-side, it will return a different variable in both cases when called.
An easy way to create the event id is to generate a random page id for each page load and then concatenate it with a sequence number that increments by one for each set of Facebook events that need to be deduplicated. Another way is to push an event with a random and unique event id to the ‘dataLayer’ for each set of Facebook tags that need to be deduplicated. This way, the Facebook hits (that require deduplication) can be triggered on the event and use the event id in the pushed object.
page_location
‘page_location’ is automatically fetched from the URL of the page, but it can still be overwritten with a custom value as in the above screenshot. This is then collected as ‘event_source_url’ by the Facebook tag on the server side.
action_source
The ‘action_source’ can be set to the following:
website
app
phone_call
chat
physical_store
system_generated
other
This field is optional and specifies the context of the hit, i.e., where the conversion took place.
You can also configure the action source in the Facebook tag on the server side. When you send the ‘action_source’, it overrides the tag setting on the server side.
User data parameters
With the proper consent and/or other controlled legal bases, you can also send user data parameters to Facebook to match the conversion with the user who performed the action.
Make sure you have the legal right to send end-user personal data to Facebook. Do not follow the instructions below blindly - ensure that you do not violate users’ privacy rights.
To ensure that user data parameters work in the server-side settings, the following field must be added to the event parameters of the GA4 tag that sends the user data:
Set the field name to ‘first_party_collection’ and the value to ‘true’.
User IP address & User-Agent string
If you wish, you can override the IP address and User-Agent sent to Facebook using the GA4 web tag. This is a good way to anonymize the request if you do not want Facebook to use the user’s IP address and User-Agent.
o override the IP address, the ‘ip_override’ field must be set. To override the User-Agent, the ‘user_agent’ field must be set. If you do not override these fields, the server-side tag will send the user’s actual IP address and User-Agent to Facebook to assist with user matching.
User data parameters in the general event schema
You can also explicitly send personal data about users to Facebook. The server-side tag obfuscates the data, so Facebook never receives the data in a readable format.
If the data is already obfuscated when sent with the GA4 tag, the Facebook tag will not obfuscate it again.
These are the parameters for which this can be set:
user_data.email_adress
user_data.phone_number
user_data.address.first_name
user_data.address.last_name
user_data.address.city
user_data.address.region
user_data.address.postal_code
user_data.address.country
This is how it would look in the GA4 web tag:
Facebook-specific parameters
There are also a number of Facebook-specific parameters that can be set. These are not automatically obfuscated.
| Parameternaam | Beschrijving |
|---|---|
| x-fb-ud-ge | Geslacht van gebruiker (husselen is nodig) |
| x-fb-ud-db | Geboortedatum gebruiker (husselen is nodig) |
| x-fb-ud-external_id | Externe ID (husselen wordt aanbevolen) |
| x-fb-ud-subscription_id | Abonnement ID (mag niet gehusseld worden) |
| x-fb-ck-fbp | De '_fbp' cookiewaarde. Zie hieronder. |
| x-fb-ck-fbc | De '_fbc' cookiewaarde. Zie hieronder. |
You can send the ‘_fbp’ and ‘_fbc’ cookie values using the parameters mentioned above. If you do not explicitly set these, and the user has those cookies in their browser, and the server-side tagging endpoint is first-party, then the Facebook tag will automatically read the cookie values from the user’s cookies.
This is how some of these parameters would look in the GA4 event tag:
Custom data parameters
Custom data parameters can also be sent to Facebook by setting them as fields in the GA4 web tag.
General parameters
There are a number of general parameters that can be set in the GA4 web tag. The server-side tag of Facebook can read these and send them to Facebook.
| GA4 parameter | Geconverteerd door de Facebook tag | Beschrijving |
|---|---|---|
| currency | currency | Valutacode van de transactie |
| value | value | Totale waarde van de transactie |
| search_term | search_string | Zoekopdracht waarmee de gebruiker op de site kwam |
| transaction_id | order_id | Unieke order-id |
This is how these parameters look in the GA4 event tag:
Items
If you collect e-commerce data on GA4, you might already have an ‘items’ array. The Facebook tag can automatically take over the contents of this ‘items’ array on the server side and turn it into a ‘contents’ array.
This is how the mapping is done:
| Intoetsen 'items' | Mappen in 'contents' | Beschrijving |
|---|---|---|
| item_id | id | Artikel-id |
| item_name | title | Artikeltitel of -naam |
| price | item_price | Artikelprijs |
| item_brand | brand | Label van het artikelmerk |
| quantity | quantity | Aantal items in de event |
| item_category | category | Label van de artikelcategorie |
This is by far the easiest way to build the ‘contents’ array. You can also send the ‘contents’ array as a custom parameter called ‘x-fb-cd-contents’.
Facebook-specific custom data parameters
You can also send a number of custom data parameters specific to Facebook. These are:
| Parameter | Beschrijving |
|---|---|
| x-fb-cd-content_category | Content categorie |
| x-fb-cd-content_ids | Content ID's |
| x-fb-cd-content_name | Content naam |
| x-fb-cd-content_type | Content type |
| x-fb-cd-contents | Contentmatrix |
| x-fb-cd-num_items | Aantal stuks |
| x-fb-cd-predicted_ltv | Voorspelde levenslange waarde |
| x-fb-cd-status | Status |
| x-fb-cd-delivery_category | Bezorgingscategorie |
Here is an example of how these parameters look in the GA4 events tag:
Test event code
When testing the Conversions API endpoint, you can use the ‘test_event_code’ parameter to collect hits on your Facebook account, including additional debugging information.
You can also set the ‘test_event_code’ parameter in the GA4 web tag. All you need to do is set the parameter as follows:
However, it might be easier to configure the ‘test_event_code’ parameter in the Facebook tag on the server side.
GA4 client running in the server container
When the ‘transport_url’ field of the GA4 web tag is set to point to your server-side endpoint, the endpoint receives a GA4 request when such a tag is triggered on the website.
If the server-side endpoint does not have a GA4 client configured, the request will fail with a ‘400’ error.
This should be sufficient to allow the server-side endpoint to claim incoming GA4 requests and process them in the format required for the Facebook tag.
Modify GA4 tags on the server side
Because you are adding new parameters to the GA4 web tag, you may not want to send them to GA4 right away. This is especially true for all preset ‘x-fb-’ parameters.
The GA4 tag on the server side does not send user data parameters (the parameters that start with ‘user_data’). So if you send a non-obfuscated email address as the ‘user_data.email_address’ parameter to your server container, it will not be processed by the GA4 tag on the server side.
But for all other parameters, you should add the parameters you want to exclude to the respective setting of your GA4 tag(s) on the server side.
As an example, you can see in the screenshot below that the ‘x-fb-cd-ge’ (for gender), ‘x-fb-cd-db’ (for date of birth), and ‘x-fb-cd-content_type’ (for content type) are not sent to GA4:
The best way to get a list of parameters processed by the GA4 client is to view the preview mode of the server container, especially the ‘Event Data’ tab for all events that trigger a GA4 tag.
Above, you can see how the three ‘x-fb-…’ parameters were generated by the GA4 client, so they need to be added to the exclusion list in the GA4 tag on the server side.
Updated on: 16/08/2024
Thank you!