Your Workspace

Custom session data

Attach your own identifiers and attributes to sessions, manage them in Seena, and let the Librarian use them safely.

Custom session data lets you attach your own key-value metadata to a visitor session as it happens. Think customer IDs, account IDs, plan tiers, experiment variants, environments, or any other small piece of context that helps you interpret a session later.

Once attached, the data shows up in Seena in four places:

  • Site settings — to see observed keys, mark a key as PII, and inspect rejected writes.
  • Session detail — as a Custom Data card on the individual session page.
  • Dashboard filters — so you can narrow session and interview lists to a cohort.
  • The Librarian — so you can ask questions like "show me enterprise sessions" or "what are Pro users struggling with?"

Good uses for custom session data

Good examples:

  • customer_id
  • account_id
  • plan_tier
  • experiment_variant
  • environment
  • signed_in

Custom session data is best for small, stable identifiers or attributes that help you slice behavior and interviews into meaningful cohorts.

It is not meant for large payloads, nested objects, event streams, or whole user profiles.

Trust model

Custom session data is client-provided context.

That makes it very useful for:

  • research and cohorting
  • stable customer or account references
  • plan, experiment, environment, or signed-in state

But it is not a verified identity system, and it should not be treated as an authorization or billing source of truth.

In practice, that means:

  • use it to help Seena interpret sessions
  • do not use it as proof that a visitor really belongs to a specific account
  • keep your own backend or data warehouse as the source of truth for entitlements, permissions, and revenue events

How to send it

There are two supported ways to attach custom session data.

1. JavaScript API

Call window.Seena.setCustomData(...) any time after the widget is available:

<script>
  window.SeenaReady = window.SeenaReady || [];
  window.SeenaReady.push(function () {
    Seena.setCustomData({
      customer_id: 'cus_123',
      plan_tier: 'enterprise',
      signed_in: true
    });
  });
</script>

Use the SeenaReady queue when you are not certain the widget script has already loaded.

2. Script tag attribute

If the values are known at page render time, you can put them directly on the script tag:

<script
  src="https://app.seenalabs.io/widget/seena.js"
  data-site-id="YOUR_SITE_ID"
  data-custom-data='{"environment":"production","plan_tier":"pro"}'
  async
></script>

This is a good fit for attributes that do not change during the session.

Merge behavior

Custom session data is merged into the current session over time.

Seena.setCustomData({ plan_tier: 'pro', signed_in: false });
Seena.setCustomData({ signed_in: true });

The session ends up with:

{
  "plan_tier": "pro",
  "signed_in": true
}

To remove a key, send null:

Seena.setCustomData({ plan_tier: null });

Limits

Phase 1 custom session data has hard caps:

  • 20 keys per session
  • 64 characters max per key name
  • 500 characters max per string value
  • 4 KB total across the whole object
  • Values must be string, number, boolean, or null

Arrays and nested objects are rejected.

Key naming rules

Keys must:

  • start with a letter
  • use only letters, numbers, _, ., :, or -

Examples:

  • valid: customer_id, plan.tier, signup:step
  • invalid: 1customer, has space, user@email

Marking a key as PII

In Settings → your Site → Custom Data, you can mark a key as PII.

Do that for keys whose values should never be sent raw to LLM providers. Typical examples:

  • customer_id
  • account_id
  • email-like identifiers
  • internal IDs that can identify a specific user

When a key is marked as PII:

  • Seena still stores it on the session
  • the session detail view masks it by default
  • the Librarian gets a tokenized form instead of the raw value
  • the UI can still detokenize it for the human reading the answer

This means you can still use the key operationally without leaking raw values into model context.

Where to find it in Seena

Site settings

Open Settings, select your site, then open Custom Data.

This is where you:

  • see every observed key
  • rename a key for display in the dashboard
  • mark a key as PII
  • inspect recent rejected writes

Session detail

Open any session and look for the Custom Data card. PII-marked values are hidden by default.

Behavior and interview filters

On the session and interview list pages, Seena can filter by exact custom-data matches. This is useful for questions like:

  • "show me only enterprise users"
  • "show me sessions from experiment B"
  • "show me signed-in traffic only"

The Librarian

The Librarian can use custom session data to find cohorts and explain what they did:

  • "Show me enterprise sessions from this week"
  • "What are Pro users struggling with?"
  • "Compare sessions where signed_in is true versus false"

What custom session data does not do yet

Today, custom session data is not yet part of interview-agent trigger conditions.

You can use it for:

  • filtering
  • session interpretation
  • Librarian queries

But you cannot yet say:

  • "only trigger this interview agent when plan_tier = enterprise"

That is planned follow-up work, not part of the current rollout.

Recommendations

Keep custom session data small and intentional.

Start with 2-5 keys that will clearly improve your analysis, for example:

  • one stable identifier like customer_id
  • one cohort field like plan_tier
  • one product context field like environment or experiment_variant

If you add too many keys too early, you create a taxonomy problem before you create useful insight.

What to read next