Realtime Events

A Realtime Event turns a live event you already collect — such as Add to Cart or Checkout Started — into something a realtime audience can react to in near real time. It tells Zeotap which live event to watch, which person that event belongs to, and which model that person sits on.

A Realtime Event is a modelling artefact, not event plumbing: it declares an entity with a relationship to a parent model, exactly as a Model or a Relationship does. That is why it lives under Sources in the left sidebar, beside Models and Relationships, rather than under Streams where the raw event collection lives.

You define a Realtime Event once and then reference it from any number of realtime audiences.

When to use a Realtime Event

Use a Realtime Event when you want an audience to respond to what a person is doing right now, rather than on a fixed refresh schedule — for example:

• reach people who performed Add to Cart in the last 30 minutes
• reach people who performed Checkout Started but have not performed Purchase in the last hour
• combine live behaviour with what you already know: Gold-tier customers who just viewed the pricing page

Anything you don’t need in near real time — a warehouse attribute, a segment, a lifetime-value threshold — stays a normal audience condition and doesn’t need a Realtime Event.

Prerequisites

• An event source (write key) that is already sending the live events you want to react to. See Event Sources.
• An event schema attached to that source, carrying a timestamp-typed field. The schema supplies the fields you bind below and the properties audiences can later filter on; a source with no schema cannot carry a Realtime Event.
• A parent model — the entity the event belongs to, such as your Users or Customers model.

How a Realtime Event is defined

A Realtime Event is defined from an event source and an event type. Every field below is picked from the fields the source’s event schema actually carries.

You provide at least one of User ID field and Anonymous ID field. Both is normal; requiring both would rule out a source that only ever carries an anonymous id.

Matching one specific action

There is no “event name” field. The name of an action — Add to Cart, Checkout Started — is an ordinary field of the event payload (event on a track event, name on page and screen), so narrowing to one action is an ordinary property condition on that field, written in the audience rather than on the declaration.

That means one Track declaration per source covers every track event you send, and each audience says which action it cares about:

performed Track where event equals Add to Cart, in the last 30 minutes

How to create a Realtime Event

You set up a source’s Realtime Events together: the mapping is answered once, and every event type you pick shares it.

1. Navigate to Sources in the left sidebar and open Realtime Events.
2. Click Create Realtime Event.
3. Event source — pick the write key the events arrive on. The properties the source’s schema carries are listed here for reference; there is nothing to pick or declare.
4. Mapping — bind the Timestamp, bind the User ID field and/or Anonymous ID field, then choose the parent model and the matching event property that maps to its primary key. If the source already has Realtime Events, these start from the most recently updated one; change anything that should differ.
5. Event types — every type not yet set up on the source starts selected. Untick the ones you don’t want and rename any you like. Types already set up on the source are shown with a link to their event and can’t be picked again.
6. Click Create. All the selected types are created together, or — if anything is refused — none of them are.

Pick a single type to create just one. A description can be added from the event’s page afterwards.

You can also start from Personalize → Membership → Overview, which lists each event source with the event types it has set up; its link opens this form with the source already chosen.

There is nothing to activate. A Realtime Event starts being tracked when an active realtime audience references it, and stops when none do — so tracking follows demand rather than a switch you have to remember.

How a person’s activity is matched

For an audience to react to a person — not one browser or one device — Zeotap needs to know which identifier each event belongs to. Each event is recorded under its user id when it carries one, and under its anonymous id otherwise. That order is fixed engine behaviour, not something you configure; what you configure is which field on your events supplies each one, so a source carrying uniqueUserID and deviceId is attributed correctly.

At evaluation time, a person’s recent activity is merged across the identifiers that have been linked together — for example when an anonymous device is later linked to a signed-in user id through an identify or alias event, including across devices when someone signs in as the same user. So behaviour from an anonymous session starts counting toward a person once that session is linked.

This linking is bounded so evaluation stays fast and a shared or bot-driven device can’t tie thousands of identifiers to one person: up to 10 linked identifiers are merged to represent a person at each evaluation (the earliest-linked ones, so the set is stable), an identifier accepts at most 100 new links an hour, and a link ages out about 90 days after it was first made. For everyday customers these bounds sit far above anything they reach. The Realtime Audiences page explains the same behaviour from the audience side.

Filtering on event properties

Beyond whether and how many times an event happened, audiences can filter on an event’s properties — for example a category, a tier, or an amount sent with the event.

You don’t declare these on the Realtime Event. The properties on offer, and the type of each, come from the event schema attached to the event source — the standard schema for a standard SDK key, or the schema you attached (manually, by upload, or promoted from discovery) for a custom one. They are resolved fresh on every read, so adding a field to the schema makes it filterable with no edit to the Realtime Event, and a field removed from the schema leaves every audience that already filtered on it intact.

Only scalar fields are filterable. A path that holds other fields — an object or an array — is marked unfilterable, because a scalar comparison against a container reads as “the value isn’t there”, which would make the condition silently false and its negation silently true.

Filters are applied to each event as it arrives, so any value works and the comparison can be a real one:

• equals / does not equal
• is any of / is none of
• greater / less than (or equal) and between
• is set / is not set

Which of these a given property offers is narrowed by that property’s declared type, exactly as it is for a batch condition — a text property is not offered >. Combine them with AND/OR groups.

Text search (contains, starts with, pattern matching) is the one family that is not available on a live event yet. See Realtime Audiences.

Using a Realtime Event in an audience

Once a Realtime Event exists, reference it in the filter builder as a performed (or not performed) condition — for example performed Track where event equals Add to Cart, in the last 30 minutes. Adding at least one realtime event condition is what makes an audience a realtime audience.

Two rules govern what happens next, and both are explained with examples on that page: keep the realtime conditions grouped together so the audience has one attribute side and one realtime side, and remember that a realtime audience is read through the Membership API and pushed through a realtime sync — it cannot be sent to a destination on a schedule, and nothing else can be built on top of it.

Next Steps

• Realtime Audiences — which realtime audiences you can build, how they go live, and how activity is linked to a person
• Event Sources — create and manage the write keys your live events arrive on
• Event Schemas — the schema that supplies the fields you bind and the properties you filter on
• Membership API — how a realtime audience is read at serve time
• Filter Builder — the visual builder where you add realtime event conditions