growth analytics/Docs
Open Hey Glancy

Events, users and sessions

Everything in Hey Glancy is built from a few kinds of messages. Knowing what each one does helps you plan what to track and keeps your reports clean.

Events

An event is something a person did: Signed Up, Project Created, Order Completed. Send one with track, and add properties with the details you'll want to filter or break down by later:

glancy.track("Order Completed", { revenue: 49.9, currency: "EUR", plan: "pro", items: 3 });

A few habits that pay off:

  • Name events as an object and a past-tense verb, in Title Case: Invoice Sent, Report Exported. Names are case sensitive, so pick a style and keep it.
  • Track meaningful actions, not every click. A short list of well-named events beats hundreds of vague ones.
  • Put the variable part in properties, not in the name: Plan Selected with { plan: "pro" }, not Pro Plan Selected.
  • Use numbers for numbers. revenue: 49.9, not "49.90 €", so Hey Glancy can sum and average them.

Properties can be strings, numbers, booleans, lists and nested objects. In reports you'll find them as properties.<name>.

Page and screen views

Page views (websites) and screen views (apps) are events too. Hey Glancy stores them as Page Viewed and Screen Viewed, with the path, URL, title and referrer (pages) or the screen name (apps). The web SDKs send page views automatically; the mobile SDKs can send screen views automatically or when you call screen().

Context

Every SDK also adds context to each event: the device, OS, browser, screen size, locale, time zone, app version, the page's UTM parameters and, when available, the country and city. That's what lets you break any report down by country or OS without tracking anything extra. In reports it's under context.<name>.

context.source says where the event was recorded: browser, app (the mobile SDKs) or server (the Next.js server client and middleware). A page view that both the Next.js middleware and the browser sent is stored once, as browser+server. Senders that don't set it, and that Hey Glancy doesn't recognise, have no source.

Users

Hey Glancy follows people across visits and devices with two ids:

  • an anonymous id, created by the SDK the first time someone visits, and kept on their device;
  • your user id, set when you call identify after someone signs up or signs in.
glancy.identify("user_42", { name: "Ana Silva", email: "ana@example.com", plan: "pro", company: "Kitbox" });

When you identify someone, Hey Glancy merges their anonymous history into the user, so the funnel from first visit to purchase stays complete. Use the same user id on every platform (your database id is ideal, never an email that might change) and a person's web, app and server events all land on one profile.

The traits you pass (name, email, plan, company…) are stored on the person's profile under Users, and can be used in any report as user.<trait>. Call identify again whenever traits change.

When someone signs out, call reset(). The SDK forgets the user, starts a new anonymous id and a new session, so the next person on a shared device isn't mixed up with the last.

Groups and aliases

  • group(groupId, traits) ties the current user to a company, team or account, for B2B products.
  • alias(userId, previousId) merges an old id into a new one, for example if you change how you identify users.

Sessions

A session is one visit: everything a person does until they've been inactive for 30 minutes. The SDKs keep track of sessions on their own and attach a session id to every event. Events sent from servers or Segment are grouped into the same person's nearest session automatically.

Sessions power the session numbers on Overview (sessions, average length, bounce rate, pages per session, entry and exit pages) and tie each session replay to the events that happened during it.

In reports, pick Session instead of an event to count sessions (by the day they started). In Insights it can also show the average duration, bounce rate or pages per session. Every event can also be filtered or broken down by its session's properties: entry and exit page, source, medium and campaign (from the utm_ parameters), referring domain, duration, page views, interactions and whether it bounced. For example, break down revenue from Order Completed by Session source to see which campaigns started the visits that sold.

Timestamps and duplicates

  • Events are stored with the time they happened. The SDKs record it on the device and send events in batches, so an event queued while offline keeps its original time. In the HTTP API, send timestamp (ISO 8601).
  • Every message has a messageId. If the same message arrives twice (after a retry, say), Hey Glancy keeps one.
  • All dates in Hey Glancy's reports are in UTC.

What's excluded

  • identify, group and alias calls are stored as system events ($identify, $group, $alias) and left out of activity counts.
  • Traffic from crawlers, uptime monitors and headless browsers is dropped automatically.