# 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 email hash 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 - Const - Widget Callback}} });
}

# User ID for logged-in Contacts Highly Recommended

Identifying logged-in users 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 - email_sha256}}) {
  civchatConfig.user_id = {{DLV - email_sha256}};
}

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

• Lowercase email — the user's email in lowercase
• Email hash — SHA-256 hash of the lowercase email
• Database ID — your internal user identifier

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 - email_sha256}}) {
  civchatConfig.user_id = {{DLV - email_sha256}};
  civchatConfig.first_name = {{DLV - user_first_name}};
  civchatConfig.last_name = {{DLV - user_last_name}};
  civchatConfig.email = {{DLV - user_email}};
  // Add any custom attributes as needed
}

For a full list of available attributes, see Additional User 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 - Const - Widget Callback}} });
    },

    // 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 - email_sha256}}) {
    civchatConfig.user_id = {{DLV - email_sha256}};
    civchatConfig.first_name = {{DLV - user_first_name}};
    civchatConfig.last_name = {{DLV - user_last_name}};
    civchatConfig.email = {{DLV - user_email}};
  }

  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:

# 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