Skip to main content
Tags are optional key-value pairs that you can attach to events in Corbado Observe. Use tags to add business context, so you can segment and filter analytics without changing your flow or subflow model.

​
1. Why use tags

Use tags when you want to answer questions like:
  • How does login conversion differ by country?
  • Does auth success differ between experiment variants (auth_variant = A vs B)?
Tags are optional. If you do not send tags, tracking still works.

​
2. Send tags from the SDK

In the Corbado Observe SDK, flow events and conversion() accept tags as an optional second argument (Record<string, string>). Flows are the carrier: configuration known at entry goes on flowStarted(), values only known on success go on flowFinished(). The last value per key wins across a flow’s events. You can attach tags:
  1. Globally via defaultTags in tracker initialization.
  2. Per event by passing a tags object to a tracking call.
For SDK installation and setup, see Integrate custom events.

​
2.1 Define global default tags

​
2.2 Pass tags per event

​
2.3 Update tags while a flow is open

Use setFlowTags() when a value becomes known between the start and finish. By default, tags also expand to child flows and later siblings until the next sibling of the same flow type. Limit expansion when a tag applies only to this journey:
Call while the target flow is open. An optional flowType selects an open flow of that type; otherwise it selects the innermost open flow. The last enriched value per key overrides the same key on that flow’s own events. Keys and values are case-sensitive; an empty key or non-string value is ignored. The flow search API can filter by up to five exact tag keys, with up to 100 values per key. Values within one key are OR-combined; separate keys and other filters are AND-combined. A date range or another selector is required.

​
2.4 Use tags in analytics

Sending a flow tag does not automatically add a filter to every dashboard. Each time series can expose up to 20 configured custom tags. Ask Corbado to include the keys you need in the relevant series. Historical buckets project their stored tag combinations onto the series’ current configured keys; a key that was never recorded is still missing. Projects default to 20 distinct tag keys, 1,000 distinct values per key and 10,000 distinct key-value pairs in total. New keys or values beyond a limit are dropped from classified flow tags; existing admitted pairs remain usable. A project also defaults to at most 1,000,000 distinct tag combinations. If a flow needs a new combination beyond that limit, its classified tag set is omitted; existing combinations remain reusable. Concurrent processing can slightly exceed these caps. Contact Corbado if your segmentation needs different limits.

​
3. Tagging best practices

  • Keep tags short, predictable and business-relevant.
  • Use strings for all values (for example is_new_user: "true").
  • Avoid high-cardinality identifiers (for example raw user IDs) as tags.
  • Prefer user references for identity mapping and tags for segmentation.

​
4. Next steps

  • Continue with Flows to model complete journeys.
  • Continue with Decisions to track explicit user and system choices.