Get started
Concepts
How data flows through BreezeIQ, and the handful of terms every other page uses.
Data flows one way, from your systems into profiles. You never write profiles directly: you send events, and BreezeIQ derives everything else from them.
Components#
From left to right, the systems an event passes through:
| Component | Role |
|---|---|
| Your systems | Website, app, order service, checkout |
| Events collector | HTTPS endpoint that accepts events (browser or server) |
| BreezeIQ | Resolves identity, folds metrics, evaluates segments ProfilesMetricsSegments |
| Control-plane API | Out: profiles, lookups, segment members |
| Webhooks | Out: segment entered / exited |
Data flow#
- Event in. You send events (
purchase,addshippinginfo, …) carrying the customer's identifiers (email, phone, cookie, device id) and properties (amount, product id, …). - Identity. BreezeIQ finds the profile those identifiers belong to, creates a new one, or merges two profiles when an event proves they are the same person.
- Metrics. Each event updates the metrics defined for it: totals, counts, last-seen times, latest values, recent-item lists.
- Segments. When a customer's metrics change, every segment that uses those metrics is re-checked. Entries and exits are recorded and sent as webhooks.
- Read. Your apps query profiles and memberships through the control-plane API at any time.
Everything is per workspace
A tenant (for example breeze) owns configuration such as event types and metric definitions. Each workspace (one store or brand) has its own profiles, segments and members. Identities never cross workspaces.
Glossary#
| Term | Meaning |
|---|---|
| Tenant | Owns configuration, such as event types and metric definitions, and its workspaces. For example breeze. |
| Workspace | One store or brand in a tenant, with its own profiles, segments and members. Tenant-wide event types and metrics apply to it automatically. |
| Workspace alias | Another name events may use for a workspace, such as a shop domain. Events sent with the alias are stored under the workspace. |
| Event | One JSON object describing one thing that happened. Browser and server events use the same format. |
| Event type | A registered, lowercase event name, such as purchase. Registration also decides how events of that type are deduplicated. |
| Identifier | A value that says who an event is about. Strong identifiers (email, phone) name a person; weak ones (cookie, device_id) name a device, which may be shared. |
| Profile | One person in one workspace, plus every identifier seen for them. A customer has an email or phone; a visitor only has cookies or device ids. |
| Metric definition | Also called a claim: "metric M is fed by event E, reading the value at path P". One metric can have a claim per event. |
| Metric | A value kept per customer and updated by events, such as total_spend or last_order_at. |
| Segment | A rule over metrics; each customer is either in or out. A temporal segment uses within_days / beyond_days, is re-checked periodically, and is marked "is_temporal": true. |
| Membership and transitions | Membership is one customer's in/out status in a segment. A transition is a change: entered or exited, with an origin (live-eval, backfill or merge-remap) saying why. |
| Webhook | A POST to your endpoint when a customer enters or leaves a segment. |
| Events collector | The HTTPS service that accepts events, from the browser or your servers. |
| Control plane | The API for configuration (event types, metrics, segments) and reads (profiles, members). |
| Tenant token | cpt_.... Can do everything in the tenant. Issued by the BreezeIQ team. |
| Workspace token | cpw_.... Read-only access to one workspace. Minted with a tenant token. |