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 know 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 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:

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.
Create a tag using the template:
Go to Tags - New, select Tag Configuration, and choose the template you just added. 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
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

CAPI field	Event data	Notes
`event_name`	`event_name` via mapping (e.g., `add_to_cart` → `AddToCart`)	Falls back to the original event name if not in the map.
`event_time`	`event_time` else `Math.round(getTimestampMillis()/1000)`	UNIX seconds.
`event_id`	`event_id`	Used for browser↔server deduplication.
`event_source_url`	`page_location`	Sent for website events.
`referrer_url`	`page_referrer`	Optional but included if present.
`action_source`	`action_source` else `data.actionSource`	Only set if provided (no default in current code).
`data_processing_options`	`data_processing_options`	Passed through as-is.
`data_processing_options_country`	`data_processing_options_country`	Passed through.
`data_processing_options_state`	`data_processing_options_state`	Passed through.

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

CAPI user_data field	Event data	Hashing / Normalization	Notes
`em`	`x-fb-ud-em` OR `user_data.email_address` OR `user_data.email`	`hashFunction()`	`x-fb-ud-em` is assumed pre-hashed; raw emails are hashed.
`ph`	`x-fb-ud-ph` OR `user_data.phone_number`	Removes `+ - space ( )` then hashes	Consider E.164 digits-only in source data.
`fn`	`x-fb-ud-fn` OR `user_data.address.first_name`	`hashFunction()`
`ln`	`x-fb-ud-ln` OR `user_data.address.last_name`	`hashFunction()`
`ct`	`x-fb-ud-ct` OR `user_data.address.city`	`hashFunction()`
`st`	`x-fb-ud-st` OR `user_data.address.region`	`hashFunction()`
`zp`	`x-fb-ud-zp` OR `user_data.address.postal_code`	`hashFunction()`
`country`	`x-fb-ud-country` OR `user_data.address.country`	`hashFunction()`
`db`	`x-fb-ud-db`	No hashing in current code	If `x-fb-ud-db` is pre-hashed it will pass through.
`ge`	`x-fb-ud-ge`	No hashing in current code	If `x-fb-ud-ge` is pre-hashed it will pass through.
`external_id`	`x-fb-ud-external_id`	No hashing in current code	If pre-hashed it will pass through.
`client_ip_address`	`ip_override`	—	Expected for website events.
`client_user_agent`	`user_agent`	—	Expected for website events.
`x-fb-ud-subscription_id`	`x-fb-ud-subscription_id`	—
`fb_login_id`	`x-fb-ud-fb-login-id` OR `user_data.fb_login_id`	—	Not hashed.
`fbc`	`x-fb-ck-fbc` OR `_fbc` cookie OR constructed from `fbclid`	—	Built as `fb.<subdomainIndex>.<ts>.<fbclid>` when `fbclid` present.
`fbp`	`x-fb-ck-fbp` OR `_fbp` cookie	—	Read from cookie if not provided.

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

CAPI custom_data field	Event data	Notes
`currency`	`currency` else `'USD'`	Defaults to USD if not provided.
`value`	`value`	Numeric value of the event (e.g., purchase total).
`order_id`	`transaction_id`	Useful for reconciliation/dedup on server side.
`search_string`	`search_term`	For Search events.
`content_ids`	`x-fb-cd-content_ids`
`content_type`	`x-fb-cd-content_type`
`content_name`	`x-fb-cd-content_name`
`content_category`	`x-fb-cd-content_category`
`contents`	`x-fb-cd-contents` (string → JSON parsed if needed) OR `items`	Builds from GA4 `items[]` as `{id, item_price, quantity}` when not provided.
`num_items`	`x-fb-cd-num_items`
`predicted_ltv`	`x-fb-cd-predicted_ltv`
`status`	`x-fb-cd-status`
`delivery_category`	`x-fb-cd-delivery_category`
`custom_properties`	`custom_properties` (string → JSON parsed if needed)	Arbitrary key/value properties merged into `custom_data`.

Best Practices

Keep 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

Relies on correct event data from GTM/GA4 setup.
Graph API rate limits apply.

References

Read the following pages for more information:

Documentation Index