# How Intempt Works — A One-Page Mental Model

# How Intempt Works — A One-Page Mental Model

This page explains **how all Intempt APIs and auto-tracked events work together** to form a complete, compliant, and flexible tracking system.

If you understand this page, you understand **how to instrument Intempt correctly**.

---

## The Big Picture

At a high level, Intempt collects **signals** about users, accounts, sessions, pages, and products.

Those signals come from two sources:

1. **Automatic events** (emitted by Intempt)
2. **Manual API calls** (sent by your application)

Together, they build a **single, coherent model** of user behavior and product data.

---

## Two Types of Signals

### 1. Automatic Signals (No Code Required)

These are emitted automatically by Intempt and reflect **what happens in the browser**.

* `intempt:html` — raw DOM interactions
* `intempt:page` — page views and exits
* `intempt:session` — session start and end

They answer questions like:

* *What did the user click?*
* *Which page are they on?*
* *When did the session start or end?*

These signals are **always contextual**, and you typically **listen to them** rather than send them.

---

### 2. Manual Signals (You Decide What Matters)

These are explicit API calls you send to Intempt when **something meaningful happens**.

They answer questions like:

* *Who is this user?*
* *What meaningful action just occurred?*
* *Which account does this belong to?*
* *Is tracking allowed?*

---

## The Core Mental Model

Think of Intempt as answering **five fundamental questions**:

| Question                        | Answered By            |
| ------------------------------- | ---------------------- |
| Who is the user?                | `identify()`           |
| What happened?                  | `track()` / `record()` |
| Which account?                  | `group()`              |
| Are multiple IDs the same user? | `alias()`              |
| Is tracking allowed?            | `consent()`            |

Everything else builds on top of this.

---

## The APIs, in Plain English

### `consent()` — Can we track?

This is the **gatekeeper**.

* Determines whether events from a user are accepted or ignored
* Should be called when consent is given, updated, or revoked
* Affects **all downstream tracking**

If consent is not valid, **nothing else matters**.

---

### `identify()` — Who is this?

This assigns a **known identity** to a user.

* Links events across sessions and devices
* Typically called after login or signup
* Turns an anonymous visitor into a known user

Call this **once you know who the user is**.

---

### `alias()` — Are these the same person?

This merges **two identifiers** into one user profile.

* Used when an anonymous ID becomes a permanent ID
* Should be called once, at the moment of certainty
* Retroactively links historical events

Think of it as **identity reconciliation**.

---

### `track()` — Something happened

This is the **default event API**.

* Used for most user actions and system events
* Flexible and lightweight
* Also used for **product catalog ingestion** when `productId` is provided

If you’re unsure which API to use, `track()` is usually the right answer.

---

### `record()` — Something important happened

This is used for **richer, structured events**.

* Supports user attributes, account attributes, and event data
* Ideal for logins, purchases, upgrades, or state changes
* Used when context matters more than frequency

Use `record()` when an event represents a **business moment**, not just an interaction.

---

### `group()` — Which account is this?

This associates users and events with an **account or organization**.

* Required for B2B and multi-tenant products
* Enables account-level analytics and segmentation
* Can carry account attributes (plan, size, tier)

Think of this as defining the **organizational context**.

---

## Where Auto-Tracked Events Fit

Auto-tracked events provide **ambient context**:

* Pages
* Sessions
* DOM interactions

They:

* require no manual instrumentation
* enrich manually tracked events
* can trigger custom logic if you listen to them

You don’t replace manual tracking with them — you **layer on top of them**.

---

## A Typical Flow (End-to-End)

1. **Session starts**
   → `intempt:session` (auto)

2. **Page is viewed**
   → `intempt:page` (auto)

3. **User clicks and interacts**
   → `intempt:html` (auto)

4. **User accepts consent**
   → `consent()`

5. **User signs up or logs in**
   → `identify()`

6. **Anonymous ID is merged**
   → `alias()` (once)

7. **User performs actions**
   → `track()` / `record()`

8. **User belongs to an account**
   → `group()`

9. **Products are synced**
   → `track()` with `productId`

Each step adds **clarity**, not duplication.

---

## One Rule of Thumb

> **Automatic events give context.
> Manual APIs give meaning.**

When both are present, Intempt can power:

* analytics
* journeys
* personalization
* recommendations
* experiments

---

## Common Mistake to Avoid

❌ Treating everything as a user event
❌ Sending product data with `userId`
❌ Calling `alias()` repeatedly
❌ Tracking before consent
❌ Overusing `record()` for simple clicks

The docs you now have exist to prevent exactly these mistakes.

---

## Final Takeaway

Intempt is not just an event collector.

It is a **behavioral model** built from:

* identity
* consent
* context
* meaning
* structure

Once you see it this way, the APIs stop feeling fragmented — they become **composable tools**.