Meta CAPI Tag Template for sGTM¶

This page describes the Meta Conversion API (CAPI) Server-Side GTM Template developed at Usercentrics. The template enables sending events from your server-side Google Tag Manager (sGTM) container directly to Meta’s Conversions API in compliance with Meta’s best practices. It is designed to improve data reliability, support event deduplication with browser-side tracking, and provide flexible handling of user data, consent, and event enrichment.

Prerequisites¶

Make sure you have the following before starting the setup:

• GTM / GA4 setup completed

  • A client-side GTM or GA4 implementation must already be in place. Read our Get started page to learn how.

  • Events must be configured to pass all required fields (user_data, currency, transaction_id, etc.) into the server-side container.

  • Meta-specific variables (x-fb-*) should be included in the GA4 → sGTM schema as recommended in Meta’s guide. The template will pick these up if they're directly defined or through some default fields in the event and user data (see sections 6 and 7 for details).

  • Notes on Required vs Optional Fields

    • Required / Strongly Recommended (per Meta CAPI docs):

      • event_name, event_time, event_id

      • action_source (should usually be "website")

      • At least one of: fbc or fbp

      • At least one hashed user data field (e.g., em, ph)

      • client_user_agent (for website events)

      • event_source_url (for website events)

    • Optional / Recommended for better matching and attribution:

      • Additional hashed user info (fn, ln, ct, st, zp, country, db, ge, external_id, fb_login_id)

      • Content parameters (content_ids, contents, content_type, etc.) for eCommerce and catalog-based events

      • Value parameters (currency, value, predicted_ltv)

    • Optional for specific use cases:

      • status, delivery_category, order_id

• Active Meta Business Account with Pixel ID.

• Access Token from Meta (System User or equivalent).

• Working server-side GTM container.

• Basic knowledge of GTM events & eCommerce data layer.

• (Optional) Browser GTM setup for event deduplication.

Template features¶

The template offers the following features:

• Standard event mapping: maps GTM event names to Meta standard events.

• Test event support: integration with the Meta Test Events tool.

• User data handling: hashing, normalization, advanced matching.

• Cookie support: _fbc, _fbp, _gtmeec.

• Event enhancement: persists user data in cookies for enrichment.

Setup instructions¶

To set up the template, follow these steps:

1. In Google Tag Manager, under Templates,  click Search Gallery. Search for "Usercentrics" and select the Meta Conversion API Tag by Usercentrics template.
   Click Add to workspace and confirm the addition again by clicking Add.

2. Create a tag using the template. To do so, go to Tags - New, select Tag Configuration, and choose the template you just imported. Configure the following:

   • Pixel ID

   • Access Token

   • Action Source (default: website)

   • Test Event Code (optional for debugging)

   • Enable/disable to extend cookies (optional)

   • Enable/disable event enhancement

3. Configure the triggers and publish your changes.

Event data mapping¶

• This template follows the recommended event schema and variable mapping provided by Meta in their GA4 → sGTM configuration guide.

• Supported (standard) events include: AddToCart, Purchase, PageView, etc.

• Custom events not listed fall back to their original gtmEvent name.

• event_id is used for deduplication and must match between browser Pixel and CAPI.

How Conversions API core fields are populated¶

User data handling¶

• Collected fields: email, phone, name, address, IP, UA, etc.

• Hashing rules: SHA-256, lowercase, trim, normalized.

  • Hashable fields go through hashFunction() (trim + lowercase + SHA-256) only when provided as raw values. If a value is already 64-char hex, it’s treated as pre-hashed and sent as-is.

How Conversions API user data fields are populated¶

Event enhancement & cookies

• If Event Enhancement is enabled, user_data is enriched from _gtmeec (base64 JSON) when fields are missing in the current event.

• On successful send:

  • If Extend cookies is enabled and fbc/fbp present, _fbc/_fbp are (re)written.

  • If Event Enhancement is enabled, _gtmeec is updated from current user_data.

Custom data handling¶

Refers to fields like currency, value, order_id, contents, etc.

How Conversions API custom data fields are populated¶

Best practices¶

Consider the following best practices:

• Keep the Graph API version configurable/up-to-date.

• Always include event_id for deduplication.

• Normalize all PII before hashing.

• Use consent gating before enriching user data.

• Test regularly with Meta’s Test Events tool.

Limitations¶

Using the template has the following limitations:

• Relies on correct event data from GTM/GA4 setup.

• Graph API rate limits apply.

References¶

Read the following pages for more information:

• Our documentation page about setting up Meta for SST.

• Meta CAPI GTM Server-Side Guide

• CAPI Event Parameters

• CAPI Customer Information Parameters