UrbanFox Docs
How-to guides

How to integrate UrbanFox clickstream tracking

Fetch your snippet configuration and deploy clickstream tracking via Google Tag Manager

This guide shows you how to deploy UrbanFox's Clickstream Analytics collector in your Google Tag Manager (GTM) container. You start by fetching the integration snippet and installing the base collector, then configure click capture and user identity handling before testing and publishing.

Before you start

Have these ready:

  • A valid access token with read:snippet permission
  • Your tenant_slug, used in the API host and tenant-scoped request path
  • Google Tag Manager installed on your website
  • A published GTM container for your website
  • GTM permissions to create Tags, Triggers, and Variables
  • The collector endpoint value provided for your UrbanFox tenant
  • Your website can push login and logout events to the GTM data layer
  • A modern browser (Chrome, Firefox, Safari)

Fetch your integration snippet

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/snippet' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

{
  "data": {
    "snippets": [
      {
        "framework": "HTML",
        "snippet": "<script src=\"https://d29oum988gdpan.cloudfront.net/clickstream-web.min.js\"></script>"
      }
    ],
    "tenant_name": "YOUR_TENANT_NAME",
    "app_id": "YOUR_APP_ID",
    "tenant_id": "YOUR_TENANT_ID"
  }
}

Copy the snippet value. Note the returned app_id and tenant_id; you use both in the GTM setup.

Install the base Clickstream collector tag

Create GTM variables for the IDs returned by the snippet API.

  1. In the left sidebar, click Variables → User-Defined Variables → New.
  2. Create a variable named App ID. Under Variable Configuration, choose Constant and set the value to the exact app_id from the snippet response.
  3. Repeat for a variable named Tenant ID, set to the exact tenant_id from the snippet response.

Now create the collector tag.

  1. Log in to Google Tag Manager and select the container for your website.

  2. In the left sidebar, click Tags → New.

  3. Name the tag Base Clickstream Collector.

  4. Under Tag Configuration, choose Custom HTML.

  5. Paste the collector script from the snippet response, then add this initialization script below it:

    <script>
  window.ClickstreamAnalytics.init({
    appId: "{{App ID}}",
    endpoint: "YOUR_COLLECTOR_ENDPOINT",
    globalAttributes: {
      tenant_id: "{{Tenant ID}}",
    },
  });
</script>

  6. Under Triggering, click the plus icon (+) and select the Initialization - All Pages trigger so the collector runs as early as possible. If it is not listed, create it: choose trigger type Initialization, set it to fire on All Pages, and save. Do not pick the built-in All Pages Page View trigger.

  7. Replace YOUR_COLLECTOR_ENDPOINT with the collector endpoint value provided for your UrbanFox tenant.

  8. Click Save.

  9. Do not change any other lines in the initialization script.

Create a click event tag

This tag records every click, including clicks on blank areas of the page, with click coordinates. Use a Custom HTML tag with a document-level listener.

Create the tag:

  1. Click Tags → New.

  2. Name it Click Event.

  3. Under Tag Configuration, choose Custom HTML.

  4. Paste this snippet:

    <script>
  document.addEventListener("click", function (event) {
    if (typeof ClickstreamAnalytics === "undefined") return;
    ClickstreamAnalytics.record({
      name: "blank_click",
      attributes: {
        xCoordinate: event.clientX,
        yCoordinate: event.clientY,
      },
    });
  });
</script>

  5. Under Triggering, click the plus icon (+) and select Initialization - All Pages (create it if it does not exist) so GTM registers the listener once, as early as possible. Do not use a Click trigger here.

  6. Click Save.

Set the user ID after login

Your website code must push a userLogin event to the GTM data layer after a successful login.

Push the login event into the data layer

Include this in your site's login success handler, immediately after the user logs in:

<script>
  window.dataLayer = window.dataLayer || [];
  // Replace 'USER_ID_HERE' with your real user-ID variable
  window.dataLayer.push({
    event: "userLogin",
    userId: "USER_ID_HERE",
  });
</script>
  • Add this code in your website, not in GTM.
  • Place it right after your login logic (for example, after a successful API response or redirect).
  • Do not modify the event: 'userLogin' name or the userId key; GTM relies on these exact identifiers.

Create the base triggers in GTM

Create two triggers:

NameTypeConfiguration
Window LoadedPage View → Window Loadedn/a
User Login (Data Layer)Custom EventEvent Name: userLogin

Combine them with a trigger group

  1. Go to Triggers → New.
  2. Name it Login Trigger Group.
  3. Under Trigger Configuration, choose Trigger Group.
  4. Add both included triggers: Window Loaded and User Login (Data Layer).
  5. Click Save.

Create the "Set User ID" tag

  1. Go to Tags → New.

  2. Name it login_success.

  3. Under Tag Configuration, choose Custom HTML.

  4. Paste this snippet:

    <script>
  var userId;
  for (var i = 0; i < window.dataLayer.length; i++) {
    if (window.dataLayer[i].userId !== undefined) {
      userId = window.dataLayer[i].userId;
      break;
    }
  }

  if (userId) {
    if (
      typeof ClickstreamAnalytics !== "undefined" &&
      typeof ClickstreamAnalytics.setUserId === "function"
    ) {
      window.ClickstreamAnalytics.setUserId(userId);
    } else {
      console.log("Clickstream Analytics is not ready");
    }
  }
</script>

  5. Under Triggering, select Login Trigger Group.

  6. Click Save.

All subsequent clickstream events are now tied to the correct user ID, without GTM needing to know how your app fetched that ID.

Clear the user ID after logout

Push a logout event from your site's logout handler:

<script>
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: "userLogout",
  });
</script>

Create a logout trigger in GTM:

  1. Go to Triggers → New.
  2. Name it User Logout (Data Layer).
  3. Under Trigger Configuration, choose Custom Event.
  4. Set Event Name to userLogout.
  5. Click Save.

Create the logout tag:

  1. Go to Tags → New.

  2. Name it logout_success.

  3. Under Tag Configuration, choose Custom HTML.

  4. Paste this snippet:

    <script>
  if (
    typeof ClickstreamAnalytics !== "undefined" &&
    typeof ClickstreamAnalytics.setUserId === "function"
  ) {
    window.ClickstreamAnalytics.setUserId(null);
  }
</script>

  5. Under Triggering, select User Logout (Data Layer).

  6. Click Save.

Test and publish

  1. Click Preview in the top-right of GTM to open the Debug Console.
  2. Enter your site URL and start the preview.
  3. Navigate between pages and verify the base collector script loads. In your browser's Network tab, look for the clickstream-web.min.js request from the snippet URL.
  4. Click anywhere and verify the blank_click event fires. In your browser's Network tab, look for a request to the tenant-provided collector endpoint URL you configured in the base tag. In Debug Console → Tags, check the Click Event tag.
  5. Log in and verify the login_success tag fires.
  6. Log out and verify the logout_success tag fires.
  7. If everything looks good, return to GTM and click Submit → Publish.

Result

Your GTM container now loads the Clickstream collector, records click coordinates, sets the user ID after login, and clears it after logout.

See also

How to handle API errors

Parse and act on RFC 7807 error responses from the UrbanFox API

How to investigate and close a fraud case

Find open fraud cases, review risk details, and close resolved cases

On this page

Before you startFetch your integration snippetInstall the base Clickstream collector tagCreate a click event tagSet the user ID after loginPush the login event into the data layerCreate the base triggers in GTMCombine them with a trigger groupCreate the "Set User ID" tagClear the user ID after logoutTest and publishResultSee also