Meta Custom Audiences Tag for Google Tag Manager Server-Side

Template Gallery Updates
1

The Meta Custom Audiences Tag for Google Tag Manager Server-Side allows you to send audience data to Meta’s advertising products using the Marketing API. This enables you to programmatically add users to or remove them from your Custom Audiences.

This tag supports three primary actions:

  • Add to Audience: Adds users to one or more specific Custom Audiences.
  • Remove from Audience: Removes users from one or more specific Custom Audiences.
  • Remove from All Audiences: Removes users from all Custom Audiences within one or more Ad Accounts.

How to use the Meta Custom Audiences Tag

  1. Add the Meta Custom Audiences Tag to your server container in GTM from the GTM Template Gallery.

  2. Select the Action you want to perform (Add to Audience, Remove from Audience, or Remove from All Audiences).

  3. Choose the authentication method:

    • Stape Meta Connection (recommended): sign in to the Meta Connection via Connections tab in the Stape admin panel. This is the easiest and recommended way to set up the authentication.
    • Own Meta Credentials: A System User access token with the ads_management permission is required. This token must be associated with the Ad Account that owns the audience. You can find more details on how to generate on the Generating a System User Access Token section.

  4. Configure the Destination Audiences or Destination Ad Accounts by providing the required IDs and, if using the Own Meta Credentials method, the Access Tokens.

  5. Configure the Audience Members section with the user data you want to send. You can provide data for a single user or multiple users in a batch.

  6. The tag will automatically hash user identifiers (like email and phone) using SHA256 if they are not already hashed.

Parameters

Main Configuration

  • Action: Choose the operation to perform.
  • Authentication Type: Own Meta Credentials or Stape Meta Connection (recommended).
    • Access Token (only if using Own Meta Credentials): A System User access token with the ads_management permission is required. This token must be associated with the Ad Account that owns the audience. You can find more details on how to generate on the Generating a System User Access Token section.
  • Destination Audiences: (For Add/Remove actions) A list of Audience IDs and, if using the Own Meta Credentials method, their corresponding Access Tokens. Each audience entry also has a Value-based Audience checkbox — enable it if the audience was created as a value-based Customer List (see Value-Based Lookalike Audiences).
  • Destination Ad Accounts: (For Remove from All action) A list of Ad Account IDs and, if using the Own Meta Credentials method, their corresponding Access Tokens.

Audience Members

The tag can be configured to send data for a single user or for multiple users at once.

  • User Mode:

    • Single User: Manually input identifiers for one user through the UI fields.
    • Multiple Users: Provide a pre-formatted array of audience members and a corresponding schema. A maximum of 10,000 audience members can be submitted per request.

  • User Identifiers (Single User):

    • A list of key-value pairs for user data, such as EMAIL, PHONE, FN (First Name), LN (Last Name), MADID (Mobile Advertiser ID), LOOKALIKE_VALUE, etc.
    • The tag automatically hashes most identifiers. MADID (IDFA/GAID) and LOOKALIKE_VALUE are exceptions and must not be hashed.
    • LOOKALIKE_VALUE is only forwarded to audiences marked as Value-based. Any LOOKALIKE_VALUE passed to non-value-based audiences is silently discarded by the tag.
    • If providing pre-hashed data, ensure it follows Meta’s normalization guidelines.

  • Audience Members (Multiple Users):

    • Audience Members Identifiers Schema: A comma-separated string or an array defining the structure of your user data (e.g., EMAIL,PHONE,FN).
    • Audience Members Array: An array containing the data for up to 10,000 users, matching the defined schema.

  • Data Processing Options:

    • For compliance with US state privacy regulations (Limited Data Use), you can enable and configure data processing options for Country and State.

Advanced Options

  • Use Optimistic Scenario: If true, the tag fires gtmOnSuccess() immediately without waiting for a response from the API. This speeds up container response time but may hide downstream errors.
  • Consent Settings: Prevent the tag from firing unless the necessary ad storage consent is granted by the user.
  • Logging: Configure console and/or BigQuery logging for debugging and monitoring requests and responses.

Value-Based Lookalike Audiences

Meta supports value-based lookalike audiences, which allow you to reach people similar to your highest-value customers. To use this feature, you must pass a LOOKALIKE_VALUE identifier alongside the other user identifiers.

:warning: Important requirements

Click to expand
  • You must create a new Customer List audience in Meta Ads Manager specifically for receiving the LOOKALIKE_VALUE. When creating the audience, you must check the option to enable value-based lookalike support — this creates a different type of Customer List.
  • An existing Customer List created without this checkbox enabled cannot be reused. Sending data with LOOKALIKE_VALUE to a non-value-based audience will result in an API error.
  • Conversely, sending data without LOOKALIKE_VALUE to a value-based Customer List will also return an error.
  • Once the value-based Customer List is populated, use it as the seed audience when creating a Lookalike Audience in Ads Manager.

To configure the tag for value-based audiences:

  1. Mark each applicable audience as Value-based by enabling the Value-based Audience checkbox in the Destination Audiences list.
  2. Include LOOKALIKE_VALUE in your user identifiers (Single User mode) or schema (Multiple Users mode).
  3. The tag will automatically include LOOKALIKE_VALUE only for audiences flagged as value-based, and will strip it from non-value-based audiences in the same tag execution.

Generating a System User Access Token (for Own Meta Credentials authentication method)

Click to expand

If using the tag with the Own Meta Credentials authentication method, it requires a long-lived System User access token for server-to-server authentication. Below are the steps to create the necessary Meta App and generate the token.

:red_exclamation_mark: You must have Admin access to that Business Manager.

:warning: Meta enforces rate limits on API calls. Make sure your usage stays within these limits to avoid errors.

  • For apps with Standard Access to the Ads Management Standard Access:
    • This is the default access level when you create a new app.
    • The rate limit is: 5000 + 40 * Number of Active Custom Audiences per hour.
  • For apps with Advanced Access to the Ads Management Standard Access feature the limit is:,
    • You must apply the app for a review to obtain this access level.
    • The rate limit increases to: 190000 + 40 * Number of Active Custom Audiences per hour.

Learn more: Rate Limiting and Rate Limiting for Custom Audiences.

Part 1: Create a Meta App

A Meta App is required to grant your system the correct permissions.

  1. Navigate to the Meta for Developers Portal and log in.
  2. Click Create App.
  3. Add an App Name and App Contact Email. Click Next.
  4. Filter by All and select the Measure ad performance data with Marketing API use case. Click Next.
  5. Choose the correct Meta Business Manager account. This should be the Business Account that owns the Ad Account and will contain the System User. Click Next.
  6. On the Publishing requirements step, click Next.
  7. On the Overview step, click Go to app dashboard.

If you are not able to create it, then you must already have a System User created and your account limit has been reached, or you don’t have the required permissions (you must be Admin of the Business Manager account).

Part 2: Generate the System User Token

Follow these steps within your Meta Business Settings.

  1. Create a System User:
    • Navigate to Users > System Users.
    • Click Add.
    • Enter a name for your System User and assign it the Employee role (Admin is not required).

If you are not able to create it, then you must already have a System User created and your account limit has been reached, or you don’t have the required permissions (you must be Admin of the Business Manager account).

  1. Assign Assets to the System User:
    The System User needs permission to access both the Ad Account and the App.

    • With the new System User selected, click Assign Assets in the hamburger menu in the top-right corner.
    • Assign the App: Select the Apps asset type, choose the app you created in Part 1, and enable the Develop app permission.
    • Assign the Ad Account: Click Assign Assets again. Select the Ad accounts asset type, choose the target Ad Account(s), and enable the Manage campaigns (ads) permission.

  2. Generate the Token:

    • With the System User selected, click Generate new token.
    • Select the App you created.
    • Choose a Permanent token (never expires) if available.
    • Under Select permissions, select ads_management.
    • Click Generate Token.
    • Important: Copy the token and store it securely (e.g., as a variable in your GTM Server Container).

:warning: Accessing Ad Accounts in Other Business Managers

A System User from one Business Manager (e.g., an Agency) cannot directly access an Ad Account owned by another (e.g., a Client). To enable this, you must establish a Partner Relationship:

  1. The Client must add the Agency’s Business ID as a partner in their Business Settings.
  2. The Client must then share their Ad Account asset with the Agency partner, granting the Manage ad account role.
  3. The Agency can now assign this shared Ad Account to its own System User.
  4. The token generated by the Agency’s System User will now be authorized to manage the Client’s audiences.

Useful resources

Open Source

The Meta Custom Audiences Tag for GTM Server-Side is developed and maintained by the Stape Team under the Apache 2.0 license.

GTM Gallery Status

:green_circle: Listed

GitHub

:green_circle: Repository

2

stape-io/meta-custom-audiences-tag — updated: view commit

  • Added support for Value-based Audience option with Lookalike Value identifier in audience configuration
  • Enhanced validation to prevent using Lookalike Value as the sole identifier and to ensure its correctness for value-based audiences
  • Updated request payload handling to exclude Lookalike Value for non-value-based audiences during API calls
  • Refactored audience and ad account ID extraction logic to better support ownAuth and Stape auth flows
  • Improved error messaging and request generation with fixed API version and refined data transformations

GTM Gallery Status

:green_circle: Listed