Basic Tracking Script

The standard approach to User.com frontend implementation uses:

1. Google Tag Manager — for deployment and configuration management
2. User.com JavaScript SDK — for tracking and widget functionality

This combination enables you to:

• Target traffic directly on your website
• Gather e-commerce behavioral data
• Capture leads using pop-ups and forms
• Personalize website content for each visitor
• Engage Contacts with Web Push notifications

While embedding User.com methods directly in your code is possible, Google Tag Manager provides significant advantages in convenience, consent management, and ease of configuration.

Prerequisites

Before implementing, ensure you have:

1. Google Tag Manager installed — This guide assumes you have a GA4 dataLayer implemented
2. User.com application set up — With your API key and subdomain ready
3. Cookie policy defined — With User.com cookies described and categorized appropriately
4. CSP policy configured — If your site uses Content Security Policy, ensure User.com domains are whitelisted
5. User ID strategy chosen — Review Key decisions → Decide on User ID if you haven't decided on lowercase email vs. database ID

For detailed information about technical prerequisites including CSP configuration, see JavaScript SDK Prerequisites.

Implementation

The basic implementation script establishes the connection between your website and User.com, enabling all tracking and widget functionality.

GTM Custom HTML tag

Create a new Custom HTML tag in Google Tag Manager. At minimum, the script only requires your API key:

<script data-cfasync="false" type="text/javascript">
  window.civchat = {
    apiKey: {{User.com - Const - App Key}}
  };
</script>
<script data-cfasync="false" src="https://{{User.com - Const - App Domain}}/widget.js"></script>

This minimal configuration will load User.com and enable basic tracking. However, for a complete implementation, we recommend adding the enhancements described below.

Recommended enhancements

DataLayer callback on load Recommended

Add a callback that pushes an event to the dataLayer when User.com has fully loaded. This allows you to sequence other GTM tags that depend on User.com being ready:

onLoad: function() {
  dataLayer.push({ event: "User.com - Widget Loaded" });
}

User ID for logged-in Contacts Highly Recommended

Identifying logged-in Contacts is critical for cross-device tracking and personalization. Add the user_id property when you have a logged-in Contact:

// Add after creating civchatConfig object
if ({{DLV - user_email_lowercase}}) {
  civchatConfig.user_id = {{DLV - user_email_lowercase}};
}

The user_id value depends on your ID strategy and can be:

• Lowercase email (recommended) — the Contact's email in lowercase
• Database ID — your internal user identifier
• Email hash — SHA-256 hash of the lowercase email (if privacy protection is needed)

See Key decisions → Decide on User ID for guidance on choosing the right approach.

Additional data for logged-in Contacts Optional

You can pass additional Contact attributes during initialization. This is useful for syncing profile data without additional API calls:

if ({{DLV - user_email_lowercase}}) {
  civchatConfig.user_id = {{DLV - user_email_lowercase}};
  civchatConfig.first_name = {{DLV - user_first_name}};
  civchatConfig.last_name = {{DLV - user_last_name}};
  civchatConfig.email = {{DLV - user_email_lowercase}};
  // Add any custom attributes as needed
}

For a full list of available attributes, see Additional contact data.

Send Code payload handler Recommended

The onPayloadReceived callback enables the "Send Code" automation module, allowing you to execute JavaScript from User.com automations:

onPayloadReceived: function(message) {
  if (typeof message === "string") {
    try {
      var sendCodeFunction = new Function(message);
      sendCodeFunction();
    } catch (e) {
      console.error("UE Error executing message as function:", e);
    }
  }
}

Complete implementation example

Here's the full script with all recommended enhancements:

<script data-cfasync="false" type="text/javascript">
  var civchatConfig = {
    apiKey: {{User.com - Const - App Key}},

    // Notify dataLayer when widget loads (for GTM trigger sequencing)
    onLoad: function() {
      dataLayer.push({ event: "User.com - Widget Loaded" });
    },

    // Enable "Send Code" automation module
    onPayloadReceived: function(message) {
      if (typeof message === "string") {
        try {
          var sendCodeFunction = new Function(message);
          sendCodeFunction();
        } catch (e) {
          console.error("UE Error executing message as function:", e);
        }
      }
    }
  };

  // Add Contact identification and data for logged-in Contacts
  if ({{DLV - user_email_lowercase}}) {
    civchatConfig.user_id = {{DLV - user_email_lowercase}};
    civchatConfig.first_name = {{DLV - user_first_name}};
    civchatConfig.last_name = {{DLV - user_last_name}};
    civchatConfig.email = {{DLV - user_email_lowercase}};
  }

  window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://{{User.com - Const - App Domain}}/widget.js"></script>

Tag configuration

1. Trigger: Use cookie_consent_update or equivalent consent trigger
2. Consent settings: Configure tag consent level based on your cookie policy

Required GTM variables

Create these variables in Google Tag Manager:

Variable Name	Type	Value
User.com - Const - App Key	Constant	Your API key from Settings → API & Integrations
User.com - Const - App Domain	Constant	Your subdomain (e.g., yourapp.user.com)
DLV - user_email_lowercase	Data Layer Variable	Lowercase email of logged-in Contact

Verification

After implementing the basic script:

1. GTM Preview mode: Verify the tag fires on your consent trigger and variables resolve correctly
2. Network tab: Look for requests to your User.com subdomain — the widget.js file should load successfully
3. Browser console: Check for any JavaScript errors related to User.com
4. Widget visibility: If you have a chat widget configured, verify it appears on your site

Once the basic script loads, User.com methods become available globally. To ensure User.com is fully loaded before executing dependent code:

if (typeof UE === 'object' && typeof userengage === 'function') {
    // User.com is loaded — safe to call methods
}

For tags that depend on User.com being ready, use the widget callback event (User.com - Widget Loaded) as a trigger condition.

Next steps

With the basic script in place, add specific tracking:

• Product events — Track e-commerce behavior and shopping funnel
• Custom events — Track interactions like logins, form submissions, and exit intent