Google Conversion Events Tag for Google Tag Manager Server-Side

The Google Conversion Events Tag for Google Tag Manager Server-Side allows you to send conversion events directly to Google's advertising platforms (like Google Ads) using the Data Manager API. This server-to-server integration ensures robust and accurate tracking of conversions, independent of client-side restrictions.

The tag is designed to handle both single and multiple conversion event uploads in a single request, with comprehensive support for user data, consent information, ad identifiers, and custom variables.

How to use the Google Conversion Events Tag

1. Choose the authentication method:

   • Stape Google Connection (recommended): sign in to the Data Manager API Connection via the Stape admin. This is the easiest way to set up the authentication. How-to.

   • Own Google Credentials: a Service Account impersonation is the simplest way to handle the authentication when using the Own Google Credentials method.

     To configure it correctly, you must:

     1. Enable the Data Manager API in a GCP Project.
     2. Create a Service Account in this GCP Project.
     3. Add the Service Account Token Creator IAM role (roles/iam.serviceAccountTokenCreator) to the Service Account.
     4. Generate a JSON Key from this Service Account (how-to) and download it.
     5. Connect the Service Account to the container using the JSON Key file:
        • If hosting on Stape, use the Service Account power-up.
        • If NOT hosting on Stape, follow these instructions.
     6. Grant the Service Account access to the product you're interacting with (Google Ads, DV360 etc.).

2. Add the Google Conversion Events Tag to your server container in GTM from the GTM Template Gallery.

3. Choose the Event Type: Conversion or Pageview.

   1. Pageview
   2. Conversion
      1. Set up your Destination Accounts and Conversion Events, specifying the Advertising Accounts Customer IDs and the corresponding Conversion Event IDs you want to send data to.
      2. Choose your Conversion Event Mode: Single to configure one event's data through the UI, or Multiple to manually provide a pre-formatted array of events.
      3. Configure the Conversion Information, User Data, and other relevant parameter groups. The tag can auto-map many of these fields from a standard GA4 or e-commerce data layer.

         ❗ If using Enhanced Conversions (user email address, user phone number etc.), ensure you do the following in Google Ads (Goals > Conversions > Settings). These settings must be active for the destination account and its manager (MCC) account, if applicable:

         1. Accept the Customer Data Terms.
         2. Enable Enhanced Conversions and Enhanced Conversions for Leads.

      4. Add a trigger to fire the tag on the appropriate server-side events (e.g., a page_view event or a purchase event).

Event Types

Pageview

This mode sets the _dm_session_attributes cookie containing a base64 JSON encoded string with the Session Attributes values for conversion event attribution and modeling.

• Default mappings:
  • Session Attribute gad_source: gad_source URL Parameter value
  • Session Attribute gad_campaignid: gad_campaignid URL Parameter value
  • Session Attribute landing_page_url: page_location Event Data value
  • Session Attribute landing_page_referrer: page_referrer Event Data value
  • Session Attribute landing_page_user_agent: user_agent Event Data value
  • Session Attribute session_start_time_usec: current timestamp of the time when the Pageview tag set the cookie

Conversion

This mode sends the conversion event.

---

Destination Accounts and Conversion Events

This is where you define which Google Ads accounts and specific conversion actions will receive the data.

• Product: The Google product to send data to (currently Google Ads).
• Operating Customer ID: The ID of the Google Ads account that will receive the conversion.
• Customer ID: The ID of the account used for authorization (e.g., an MCC account). If the operating account is the same as the authorizing account, this can be the same.
• Conversion Event ID: The unique ID for the conversion action in Google Ads.

---

Conversion Event Mode

You can send data in two ways:

• Single Conversion Event: Configure the parameters for a single conversion directly in the tag's UI fields.
• Multiple Conversion Events: Provide a complete, pre-formatted JSON array containing data for up to 2000 conversion events. This is useful for batch uploads.

---

Conversion Information

This section contains the core details of the conversion.

• Parameters: Includes Transaction/Order ID, Event Timestamp, Currency, and Conversion Value.
  • Auto-mapping: If enabled, the tag will attempt to automatically populate these fields from the incoming event data (e.g., transaction_id, currency, value).

---

User Data

This section is crucial for matching the conversion to a user. You can provide multiple identifiers to improve match rates.

• Identifiers: Includes Email Address(es), Phone Number(s), and User Address (First Name, Last Name, Region, Postal Code).
  • Auto-mapping: If enabled, the tag will automatically pull user data from common event data keys (e.g., user_data.email).
• Hashing & Normalization: The tag automatically normalizes and SHA-256 hashes user identifiers if they are provided in plain text, following Google's formatting guidelines.

---

Ad Identifiers

This section allows you to send click identifiers for attribution. It's as important as the User Data parameters for matching the conversion to a user.

• Click IDs: gclid, gbraid and wbraid.
  • Auto-mapping: If enabled, the tag will automatically pull Click IDs from, in this order, Event Data > URL Parameter > Server Cookie > JavaScript Cookie.
• Landing Page Parameters and Session Attributes: Landing Page User Agent, Landing Page IP Address and Session Attributes
  • Auto-mapping: If enabled, the tag will automatically pull Session Attributes from, in this order: session_attributes Event Data value > _dm_session_attributes Common Cookie value > _dm_session_attributes cookie set by the Pageview event of this tag.

---

Device Information

You can include device details for the conversion event.

• Parameters: User Agent and IP Address.

---

User Properties

This section provides more context about the customer.

• Parameters: Customer Type (New, Returning, or Re-engaged) and Customer Value Bucket (Low, Medium, or High).

---

Cart Data

This section allows for sending product-level details for e-commerce transactions.

• Parameters: Merchant Center ID, Feed Label, Feed Language Code, Transaction Discount, and a list of Items with their Item ID, Merchant Product ID, Item Quantity, and Price.
  • Auto-mapping: If enabled, the tag will automatically pull Items from Event Data.

Note: it's required to send at least the Merchant Product ID for each item.

---

Custom Variables

This section allows you to send any additional key-value pairs for custom reporting.

• Parameters: A list of Variable ID, Variable Value, and optional Destination References.

How to obtain the Variable ID

⬇️ Click to expand ⬇️

There are 2 simple ways to obtain the Custom Variable ID.

1 - Using Scripts in Google Ads UI

1. Open Google Ads.
2. Go to Tools > Bulk Actions > Scripts. Tip: use the search bar at the top.
3. Click the + button to a new script and give it a descriptive name.
4. Paste this code in the script code block:

function main() {
const query = `
    SELECT
    conversion_custom_variable.id,
    conversion_custom_variable.name,
    conversion_custom_variable.tag,
    conversion_custom_variable.status
    FROM conversion_custom_variable
`;

const searchResults = AdsApp.search(query);

console.log('------------------------------------------------------------------------------------------------------');
console.log('# CUSTOM VARIABLES INFORMATION #');
console.log('------------------------------------------------------------------------------------------------------');
console.log(
    'NAME'.padEnd(30) + ' | ' +
    'TAG STRING'.padEnd(20) + ' | ' +
    'STATUS'.padEnd(18) + ' | ' +
    'ID (Use this in GTM!)'
);
console.log('------------------------------------------------------------------------------------------------------');

let count = 0;
while (searchResults.hasNext()) {
    const row = searchResults.next().conversionCustomVariable;
    const status = row.status;
    const name = row.name.padEnd(30);
    const tag = row.tag.padEnd(20);
    const id = row.id;
    console.log(`${name} | ${tag} | ${status.padEnd(18)} | ${id}`);
    count++;
}

if (count === 0) console.log('No custom variables found in this account.');

console.log('------------------------------------------------------------------------------------------------------');
}

5. Give it the requested permissions through the Authorize button.

6. Click Preview. There's no need to click Run.

7. Go to the Logs tab. This is where the Custom Variable ID will show up.

   Example:

   

8. Use the Custom Variable ID in the Variable ID field of the tag Custom Variables section.

2 - Using DevTools

1. Open Google Ads.

2. Go to Goals > Conversions > Custom Variables. Tip: use the search bar at the top.

3. Open DevTools and go to the Network tab.

4. In the Network tab, search for ConversionCustomVariableService/List.

5. Reload the Custom Variables page.

6. The Network panel should display a request (filtered by the filter added in step 4).

7. Click on this request and go to the Response tab.

8. The Custom Variable information will be in the array value of the key named "1". Each item in the array is a custom variable.

9. The Custom Variable ID is the key "1" inside the object. The Custom Variable Name is the key "4".

   Example:

   

10. Use the Custom Variable ID in the Variable ID field of the tag Custom Variables section.

---

Advanced Options

• Validate Only: If true, the request is validated by the API but not executed. This is useful for debugging.
• 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.
• Request-level Consent: Apply adUserData and adPersonalization consent statuses to all users in the request. This can be overridden at the user level when using the "Multiple Users" mode.
• 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.

Useful Resources

• Step-by-step guide on how to configure Google Conversion Events Tag
• Stape's Data Manager API Connection
• Data Manager API for Conversion Events
• Conversion Event definition
• User Identifiers Normalization Guidelines
• Session Attributes: [1] and [2]

Open Source

The Google Conversion Events Tag for GTM Server-Side is developed and maintained by the Stape Team under the Apache 2.0 license.