Tagging

Tags let you label all events from a script instance with a string identifier. This is useful for A/B testing, deploy labeling, cohort segmentation, and any scenario where you want to slice your analytics by a custom dimension that applies to the entire page.

If you need Rybbit to choose a value at runtime, gradually roll out a feature, or serve remote config, use Feature Flags instead.

How It Works

Add a data-tag attribute to your Rybbit script tag. Every event (pageviews, custom events, outbound clicks, etc.) sent from that page will include the tag value, which is stored in ClickHouse and available as a filter in the dashboard.

<script
  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
  defer
  data-tag="variant-a"
></script>

The tag is a simple string of at most 256 characters. The script doesn't shorten it: a longer tag makes the server reject every event from the page with 400, so nothing is tracked. If data-tag is not set or is empty, no tag is stored.

Older snippets that pass the site ID as data-site-id instead of ?siteId= still work.

Use Cases

A/B Testing

Serve different script tags to different user groups and compare behavior:

<!-- Variant A -->
<script src="https://app.rybbit.io/api/script.js?siteId=1" data-tag="homepage-v2-a" defer></script>

<!-- Variant B -->
<script src="https://app.rybbit.io/api/script.js?siteId=1" data-tag="homepage-v2-b" defer></script>

Then filter by tag in the dashboard to compare metrics between variants.

Deploy / Release Labeling

Tag events with the current deploy version to correlate releases with changes in user behavior or errors:

<script
  src="https://app.rybbit.io/api/script.js?siteId=1"
  defer
  data-tag="v2.4.1"
></script>

Cohort Segmentation

Label traffic from different sources, campaigns, or user segments:

<script
  src="https://app.rybbit.io/api/script.js?siteId=1"
  defer
  data-tag="beta-users"
></script>

Filtering by Tag

Once events with tags are flowing in, you can filter by tag anywhere in the dashboard:

Click the filter button in the dashboard header
Select Tag from the filter parameter dropdown
Choose an operator (is, is not, contains, etc.)
Enter the tag value

The tag filter works on all dashboard pages including overview, pages, referrers, events, users, funnels, and goals.

API Usage

When sending events via the HTTP API, include tag in the request body:

{
  "site_id": "YOUR_SITE_ID",
  "type": "pageview",
  "hostname": "example.com",
  "pathname": "/",
  "tag": "variant-a"
}

Important Notes

Each script instance can only have one tag. If you need multiple dimensions, consider using custom event properties instead.
Tags are set at the script level, not per-event. All events from a page load share the same tag.
The tag value is stored as-is (no hashing or transformation).
Empty or missing data-tag attributes result in no tag being stored.

Related Documentation:

On this page