Conversions API for Server-Side Google Tag Manager (GTM)

The Conversions API is designed to create a direct connection between your marketing data and the systems which help optimize ad targeting, decrease cost per action and measure results across Meta technologies. You can configure a server that you set up on the Google Cloud Platform (GCP) to send website events through the Conversions API. With this setup, after you configure the Google Analytics 4 (GA4) Web Tag, you can send that data to your own server hosted on Google Cloud Platform (GCP) and eventually to Meta through the Conversions API.

The Conversions API Tag is written and maintained by Meta based on the Google Custom Tag Template. Please reach out to Google with any questions you have about setting up Google products or Google’s developer documentation.

This document outlines the following:

  • Prerequisites, including how to create a server container
  • How to configure the container to support your implementation using the GA4 Web Tag
  • How to send data from your website to your GCP server
  • How to share that data with Meta via the Conversions API
  • Frequently asked questions

Prerequisites

Before proceeding with this integration, we recommend that you:

  1. Get familiar with the Conversions API integration and the best practices for setup
  2. Get familiar with Server-Side Tagging and Custom Tag Template.
  3. Deploy a server container using your preferred cloud provider. For default GCP deployment, you can refer to the following guidance. If your system uses a version older than GA4, you will need to upgrade your existing tag manager setup to use GA4 before proceeding with this integration.

Integration

Create a GTM Server Container

You will need to configure a server container on GCP and a web container:

  • Web container: If this is your first time using GTM, start with installing a web container to your account. Learn more here.
  • Server Container on GCP: You will need to create a server container on GCP in Workspace on your GTM Portal to set up a tagging server URL. Learn more about this step.

Self-Serve Installation in Events Manager

For simple setup, advertisers can navigate to Meta Business Manager > Events Manager > Partner Integrations > Google Tag Manager (Server-side) to onboard Conversions API. This self-serve onboarding flow takes a few inputs like your existing Meta Pixel ID, Google Measurement ID, and other GTM server containers and deploys necessary configurations on your GTM containers. You will also need to update your existing website code to pass additional event details along.

Note: This is a simplified setup. If you need more customizations, please follow the steps below for manual installation.

Manual Installation

Configure web and server containers

  1. On your web container, create the following artifacts:
    • GA4 Configuration to configure your tagging server URL, and
    • GA4 Event to configure event schema to be delivered to the server.
  2. On your server container, create the following artifacts:
    • GA4 Client, a listener for the event that fires the event to Facebook, and
    • Meta Conversions API Tag, a server-side tag that converts the standard event model from GA4 Client to Conversions API event schema and sends it to graph.facebook.com.

Step 1: GA4 Configuration – Configure Your Tagging Server URL


Create a Data Layer Variable for each of the GTM common event schema's user_data parameters. Learn more about setting up data-layer variables. For example, to pass an email address to Server-Side GTM, create a variable, (for example, user_data_email_address) that can be mapped to the Data Layer Variable Name, eventModel.user_data.email_address.

The list below shows all the mappings for Meta and GTM user_data parameters and their general priority in helping increase Event Match Quality. To get the most out of Meta ads, we recommend using the Conversions API best practices when you set up an integration. If you have already set up the Conversions API, we recommend considering these best practices to improve your existing setup. The Conversions API best practices can help improve your ad performance by lowering your cost per action.

Conversions API Meta ParameterGTM Data Layer Variable NamePriority

email_address(em)

eventModel.user_data.email_address

Highest

phone_number(ph)

eventModel.user_data.phone_number

High

first_name(fn)

eventModel.user_data.address.first_name

Medium

last_name(ln)

eventModel.user_data.address.last_name

Medium

city(ct)

eventModel.user_data.address.city

Medium

state(st)

eventModel.user_data.address.region

Medium

postal_code(zip)

eventModel.user_data.address.postal_code

Medium

country(country)

eventModel.user_data.address.country

Medium

Step 2: GA4 Event – Configure event schema to be delivered to the server


  • Configure your web container to send your website data to the created tagging server. Learn more about how to configure the Google Analytics: GA4 Configuration Tag. Set your transport_url as the tagging server URL.
  • Add the Google Analytics: GA4 Event Tag to your Workspace from the Template Gallery:
    • Set up an Event Name for the tag. You can set this as a static value or configure it to read from a variable. Learn more.
    • In the Event Parameters section:
      • Set the first_party_collection flag to true. You must do this to be able to pass the user_data parameters to the Server-Side GTM.
      • Map each of the parameters you want to configure. The variable name will be read from the event using a common event schema. For example, to set up email as an event parameter, you have to define it as Parameter Name: user_data.email_address and set up the Value as the variable name that reads the email_address (defined earlier in Section 1).

Step 3: Create a listener for the event that fires the event to Meta


Every GTM server-side container comes with a default GA4 Client for listening to events configured from their GA4 Web Tag. The GA4 Client listens to the /g/collect route on your tagging server URL and sends the eventModel to the downstream tag.

Step 4: Create Meta Conversions API Tag, a server-side tag that converts the standard event model from GA4 Client to Conversions API event schema and sends it to graph.facebook.com


To send the event to the Conversions API, you need to install the Meta Conversions API Tag from the Template Gallery. This tag can be set up to be triggered on events received by the GA4 Client (in the previous step) and sent to the Conversions API. To install the Meta Conversions API Tag, you will need to have a Pixel ID, access token and specify the action source as “website”.

Deduplication

We recommend that you use a redundant event setup and share the same events from both the Conversions API and your Meta Pixel. Ensure that both events use the identical event_name and that either event_id or a combination of external_id and fbp are included.

This will allow Meta to properly deduplicate events and reduce double reporting of identical events. Learn more about deduplication, when it’s necessary and how to set it up. The external_id and fbp are alternative solutions for deduplication and help also to improve the quality of setup. We recommend including these three parameters whenever possible.

GTM has multiple ways to set up a parameter with the same value across a browser tag and a server tag. One way is to use the same GA4 event as the trigger to fire your Meta Pixel tag and server event. To achieve this:

  • Use the same trigger for your Meta Pixel Custom HTML Tag and GA4 Event Tag with the same trigger condition for both tags. For example, you could define a trigger condition based on the gtag event name, as explained in the Send data from your website to your GCP server section of this doc.
  • Use the same event_id in both tags:
    1. Set a unique ID from Client: Set a custom parameter (x-fb-event_id) from the gtag event. Generate a unique ID (per event) on the website using a Javascript method (or using Google Tag Manager custom Javascript variable) and set the value in the event as:
    2. gtag('event', 'purchase', {
       'x-fb-event_id': generateEventId(),
      ...:...
      
       });
      You can create a variable that points to the custom Javascript shown above. Whenever the var is referred, the below Javascript is loaded in line:
      function() {
      var gtmData = window.google_tag_manager[{{Container ID}}].dataLayer.get('gtm');
      return gtmData.start + '.' + gtmData.uniqueEventId;
      }
    3. Create and populate a Data Layer Variable: You can create your own variable on the web container to read the value from x-fb-event_id. You can do this by creating a new Data Layer Variable, for example, FBEventIdVar, with the Data Layer Variable Name as eventModel.x-fb-event_id.
    4. Once the variable is set, you have the variable to plug into the web event in your custom HTML tag, and the server event as an additional GA4 Event Parameter.
    5. On the web, you can set up your Meta Tag on Google Tag Manager web containers to read event_id from a variable.
    6. fbq('track', Purchase, {..}, {eventID: FBEventIDVar });
      Configure the GA4 Event to send an extra parameter, named x-fb-event_id, set to the FBEventIdVar variable.

Send Data from Your Website to Your GCP Server

After configuring your web and server containers, you can send a sample event from your website to verify the server event. A sample event with the configured parameters may look something like this

 gtag('event', 'purchase', 
  {
    'x-fb-event_id': generateEventId(),
    'transaction_id': 't_12345',
    'currency': 'USD',
    'value': 1.23,
    user_data: {
      email_address: '<HASHED_DATA>',
      phone_number: '<HASHED_DATA>',
      address: {
        first_name: '<HASHED_DATA>',
        last_name: '<HASHED_DATA>',
        city: '<HASHED DATA>',
        region: '<HASHED_DATA>',
        postal_code: '<HASHED_DATA>',
        country: '<HASHED_DATA>'     
      },    
    },
    items: [
      {
        item_id: '1',
        item_name: 'foo',
        quantity: 5,
        price: 123.45,
        item_category: 'bar',
        item_brand: 'baz'     
      }
    ], 
  });      
     

Once the event is triggered, you should see a request sent to, for example, sample link: www.analytics.example.com/g/collect, with the configured parameters. You can add test event code to the Meta Conversions API Tag to verify events sent to the Conversions API.

Frequently Asked Questions

Are there plans to add the capability to send custom parameters? If yes, when will this be available?
A: We have added mapping for most of the Conversions API’s standard custom parameters that are supported in GTM’s schema. We have also provided custom mapping. See here for more.

Is a single server or cluster able to run multiple containers?
A: Currently, GTM supports only 1:1 mapping. Read recommendations on how to organize your containers.

Does Server-Side GTM require a browser-based tag to emit events?
A: Yes

Does the GTM Conversions API integration work with cloud hosting solutions other than GCP?
A: The GTM Conversions API integration should work with GCP or any other platform of your choosing. Read more here about manual provisioning.