Session Tags & Custom Metadata

Tags let you attach any custom metadata you have about a user or what's happening on your site to the session recording. Every session recording in Inspectlet can carry an unlimited number of tags, and once a tag is on a session you can search by it, display it as a column in the session recordings table, get real-time notifications when it fires, and use it to power integrations.

Tags are the main way to bring your own context into Inspectlet. If you only want to associate a session with a nickname like an email or user ID, see Identifying Users instead — identify gives the session a label in the dashboard, while tagSession stores arbitrary metadata you can filter, sort, and alert on.

What to tag

There are three common categories of things worth tagging:

  • User traits – Anything you already know about the visitor. Common keys include userId, email, plan, accountAge, pointsEarned, signupDate, role.
  • Custom events – Moments that matter in your product, like "viewed checkout", "completed purchase", "hit paywall", "ran into error". Tags make these sessions easy to pull up later.
  • Third-party context – Information from other systems you want paired with the recording, such as the current A/B test variation, a marketing campaign name, or a CRM record ID. See Integrating HubSpot with Inspectlet for one concrete example of tagging sessions with an ID from another service.

The tagSession API

Use the tagSession command on Inspectlet's JavaScript queue to attach tags from your site:

__insp.push(['tagSession', <string | object>]);

The second argument can be either a simple string or an object of key/value pairs. Tags are attached to the current session and persist for the entire recording, so you only need to call tagSession once per tag. Calling it multiple times — for example, on every page load — is safe; duplicate tags are ignored.

Tagging with a string

When you just want to mark that something happened, a plain string works:

__insp.push(['tagSession', "viewed checkout"]);

Tagging with key/value pairs

When your data has structure, pass an object. This lets you search for the key alone or narrow to a specific value:

__insp.push(['tagSession', {email: "john@example.com"}]);

The above creates a tag with the key email and the value john@example.com.

Sending multiple tags at once

You can send as many key/value pairs as you want in a single call:

__insp.push(['tagSession', {email: "john@example.com", userId: 1258, pointsEarned: 42}]);

This is equivalent to calling tagSession three times, one per key.

Updating a tag's value

Calling tagSession again with the same key replaces the previous value for that session. This is useful for tags that change while the user is on the site:

__insp.push(['tagSession', {converted: false}]);

// ...later in the same session, after the user converts:
__insp.push(['tagSession', {converted: true}]);

The recording will end up with converted: true.

Searching and filtering by tag

Once a session is tagged, you can find it from the Session Recordings page:

  1. Click Add Filter and choose Tagged With.
  2. Enter the tag key, or the key/value pair, you want to match.

Popular tags appear as autocomplete suggestions, which makes it easy to discover what's already in your data.

Showing tags as columns

Any tag can be surfaced as its own column in the session recordings table, so you can scan tag values at a glance without opening each recording. See Loading Custom Columns from Tag Data in Session Recordings for the steps.

Real-time notifications on tags

If you want to be alerted the moment a specific tag fires — for example, when someone tags a session with error or enterprise-signup — you can configure tag-triggered notifications delivered by email, Slack, or webhook. See Event Alerting and Notifications.

More examples

Tagging a purchase

Fire this on the order confirmation page so you can pull up all sessions that ended in a sale:

__insp.push(['tagSession', "purchase"]);

Tagging an A/B test variation

Pair recordings with the variant the visitor saw so you can compare behavior between cohorts:

__insp.push(['tagSession', {abTest: "checkout-v2", variant: "B"}]);

Tagging an application error

Call this from your global error handler to make error sessions trivial to find:

window.addEventListener('error', function(e){
    __insp.push(['tagSession', {error: e.message}]);
});

Tagging the full user identity

Send everything you want to search by in one call as soon as the user is known:

__insp.push(['tagSession', {
    userId: 1258,
    email: "john@example.com",
    plan: "pro",
    signupDate: "2024-03-12"
}]);

Tips and gotchas

  • Tag keys and values are case-sensitive — keep your naming consistent across your codebase so filters and custom columns line up.
  • Tag values are stored as strings. Numbers and booleans you pass in will be stringified, which is fine for search but worth knowing when building columns.
  • Never send secrets, passwords, or other sensitive PII as tag values — tags are visible to anyone on your Inspectlet account who can view sessions.
  • Calling tagSession with an empty object ({}) is a no-op and won't record anything.
  • tagSession can be called at any point in the session, including before Inspectlet has finished loading — calls made early are queued on __insp and flushed once the script is ready.