Conversions API for Server-Side Google Tag Manager

The Conversions API can be used to collect key web and offline event data shared from a server that you set up on the Google Cloud Platform (GCP). Conversions API integration is built by leveraging the GA4 Web Tag and GA4 Server Client. Learn more about the Conversions API and Server-Side Google Tag Manager (GTM).

This document outlines the steps required to:

  • Create a server container
  • Configure data collection using Google Analytics 4 Web Tag
  • Send data to your GCP server
  • Share that data with Facebook via the Conversions API

Configure Your GTM Portal

To complete your integration, you will need to configure a GCP server container and a web container.

GCP Server Container: You will need to create a server container on the GCP in Workspace on your GTM Portal to set up a tagging server URL. Learn more about this step.

Configure Your Web and GCP Server Containers

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.

On your server container, create the following artifacts:

  • GA4 Client, a listener for the event that fires the event to Facebook, and
  • Facebook 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.

On the Web Container

  1. 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.

  2. Here’s a list of all the mappings for Facebook and GTM user_data parameters:

    Facebook ParameterGTM Data Layer Variable Name

    email_address(em)

    eventModel.user_data.email_address

    phone_number(ph)

    eventModel.user_data.phone_number

    first_name(fn)

    eventModel.user_data.address.first_name

    last_name(ln)

    eventModel.user_data.address.last_name

    city(ct)

    eventModel.user_data.address.city

    state(st)

    eventModel.user_data.address.region

    postal_code(zip)

    eventModel.user_data.address.postal_code

    country(country)

    eventModel.user_data.address.country

  3. 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.

  4. 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 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).

On the Server Container

GA4 Client: 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.

To send the event to the Conversions API, you need to install the Facebook 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 Facebook Conversions API Tag, you will need to have a pixel ID, access token and specify an action source.

On Your Website

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: 'ABC@XYZ.com',
      phone_number: '1234567890',
      address: {
        first_name: 'john',
        last_name: 'smith',
        city: 'menlopark',
        region: 'ca',
        postal_code: '94025',
        country: 'us'     
      },    
    },
    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 Facebook Conversions API Tag to verify events sent to the Conversions API.

Deduplication

We recommend that you use a redundant event setup and share the same events from both the Conversions API and your Facebook 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 Facebook 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.

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 Facebook pixel tag and server event. To achieve this

  • Use the same trigger for your Facebook 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 earlier in the On Your Website 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 and set the value in the event as:
    2. gtag('event', 'purchase', {
       'x-fb-event_id': generateEventId(),
      …:...
       });
    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 would 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 Facebook Tag on Google Tag Manager web containers to read event_id from a variable.
    6. fbq('track', Purchase, {..}, {eventID: FBEventIDVar });
    7. On the GA4 event, configure to send an extra parameter, named x-fb-event_id, set to the FBEventIDVar variable.