Google Tag Manager (GTM)

Overview

This guide explains how to integrate VWO Feature Experimentation with Google Tag Manager (GTM) to trigger custom tracking events, without requiring client-side SDK initialization.

By following this flow, you can:

Generate consistent VWO UUIDs on your backend
Pass them securely to your frontend
Use GTM to trigger VWO tracking events on clicks, form submissions, or any custom user interaction

Step 1 — Install the VWO SDK

Install the official VWO Feature Experimentation SDK in your backend:

npm install vwo-fme-node-sdk

Step 2 — Generate a VWO UUID in Your Backend

Use the SDK’s getUUID() method to convert your user’s ID into a VWO-compatible UUID. This ensures a consistent identifier across all tracking events.

import { getUUID } from 'vwo-fme-node-sdk';
const userId = 'sample_user_id';
const accountId = 'sample_account_id';

const vwoUuid = getUUID(userId, accountId);
console.log(vwoUuid); // e.g., "A1B2C3D4E5F6..."

Next: Pass this UUID to your frontend via an API response.

Step 3 — Pass the UUID to the Frontend (via API Response)

Either pass the generated UUID as a response from a new API endpoint, or as part of an existing API endpoint

{
  "user": {
    "id": "sample_user_id",
    "vwo_uuid": "A1B2C3D4E5F6..."
  }
}

📘

Your frontend application can fetch this data and store it globally for GTM to use.

Receive the VWO_UUID from backend and set the VWO_UUID

fetch('/api/user-data')
  .then(res => res.json())
  .then(data => {
    window.VWO_UUID = data.user.vwo_uuid;
    // GTM tag can now use this UUID for VWO tracking
  });

Step 4: Trigger Setup in GTM

Trigger Type: Choose your event trigger (e.g., Click – All Elements or Form Submission).
Conditions: Specify rules (e.g., Click Text contains "Buy Now").
Variables: Add VWO UUID as a GTM variable (from window.VWO_UUID).

This ensures that the same user UUID is passed to VWO during every event.

Step 5 — Create an Event Tag in GTM

In Google Tag Manager, create a Custom HTML Tag. This tag will trigger a VWO event when an action (e.g., a button click) occurs.

Paste the following script into your GTM Custom HTML field:

🧾 Event Tag Code

🚧
Make sure to replace <ACCOUNT_ID> and <EVENT_NAME> with your actual values in the below code.

<script>
(function() {
    // ------------------------
    // CONFIGURE THESE VALUES
    // ------------------------
    var VWO_ACCOUNT_ID = "<ACCOUNT_ID>";   // replace with your VWO account ID
    var EVENT_NAME = "<EVENT_NAME>";       // replace with your custom event name
    var PAGE_TITLE = document.title;
    var PAGE_URL = window.location.href;
    var REFERRED_URL = document.referrer || "";
    var VWO_UUID = {{VWO UUID}}; // replace if needed

    // Generate timestamps
    var timestampMs = new Date().getTime();
    var timestampSec = Math.floor(timestampMs / 1000);

    // Construct payload
    var payload = {
        d: {
            msgId: VWO_UUID + "-" + timestampMs,
            visId: VWO_UUID,
            event: {
                name: EVENT_NAME,
                time: timestampMs,
                props: {
                    page: {
                        title: PAGE_TITLE,
                        url: PAGE_URL,
                        referredUrl: REFERRED_URL
                    },
                    isCustomEvent: true,
                    vwoMeta: {
                        source: "client"
                    }
                }
            },
            sessionId: timestampSec
        }
    };

    // Send POST request
    var endpoint = "https://dev.visualwebsiteoptimizer.com/events/t?en="
      + encodeURIComponent(EVENT_NAME)
      + "&a=" + encodeURIComponent(VWO_ACCOUNT_ID);

    var xhr = new XMLHttpRequest();
    xhr.open("POST", endpoint, true);
    xhr.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
    xhr.onreadystatechange = function() {
        if (xhr.readyState === 4) {
            if (xhr.status >= 200 && xhr.status < 300) {
                console.log("✅ VWO custom event triggered successfully: " + EVENT_NAME);
            } else {
                console.error("❌ Error triggering VWO event", xhr.responseText);
            }
        }
    };
    xhr.send(JSON.stringify(payload));
})();
</script>

Example Usage of the Integration

Backend

Generates a unique VWO UUID for each user by calling getUUID(userId, accountId) from the VWO FME SDK (any supported SDK can be used — see list of all SDKs). Below is the sample code for Node.js application.

import { getUUID } from 'vwo-fme-node-sdk';

app.get('/api/user-data', (req, res) => {
  const userId = req.user.id;
  const accountId = 'sample_account_id';
  const vwoUuid = getUUID(userId, accountId);

  res.json({
    user: {
      id: userId,
      vwo_uuid: vwoUuid
    }
  });
});

Frontend (JavaScript)

Fetches the user data from the backend, stores the vwo_uuid in window.VWO_UUID, making it available for VWO or GTM tracking.

fetch('/api/user-data')
  .then(res => res.json())
  .then(data => {
    window.VWO_UUID = data.user.vwo_uuid;
    // GTM tag can now use this UUID for VWO tracking
  });

GTM Trigger
Use the same code to trigger custom HTML using events as mentioned in Step 5.