Core concepts

A small handful of nouns covers everything Tracera does. Learn these once and the API, the portal, and the docs all suddenly make sense.

The hierarchy

Platform
└── Tenant            (organisation / customer / GoTrust itself)
    └── Brand          (e.g. "brand-a", "brand-b")
        └── Property   (a tracked app or site, e.g. brand-a.com web)
            └── Domain(s) / bundle-IDs / app-IDs

Hard isolation lives at the tenant level. Nothing in one tenant can ever query, see, or leak into another. Brands and properties are organisational; they share infrastructure inside their tenant but get separate dashboards and tokens.

Event

The atomic unit of data. An event is a JSON blob with at minimum an event type (pageview, event, screen) and a property public key. The server enriches it with a server timestamp, a coarse country/region, a device class, and a daily-rotating visitor hash. See the full schema at Ingest API.

Visitor

Tracera does not store a persistent visitor identifier. The visitor field on every event is:

visitor_id = sha256(daily_salt || domain || ip || user_agent)

The daily_salt rotates every 24 hours and is destroyed at rotation. After rotation, no amount of compute can reconstruct yesterday's hash. That's why we can show "unique visitors" without ever knowing who anyone is. See Privacy model.

Session

A session is a run of events from the same visitor with no more than 30 minutes between consecutive events. Sessions are derived server-side, never stored on the client. They reset across day boundaries because the visitor hash does.

Property type

Public key vs. API token

Two different things, often confused:

• Public ingest key (pk_…) — safe to embed in client code. Authorises writes to one property only.
• API token (tk_…) — secret. Authorises reads / management actions according to its scope and capabilities. Server-side only.

RBAC

Six default roles, scoped at the right level: platform_owner, tenant_admin, brand_manager, analyst, viewer, service_account. Each role maps to a fixed set of capabilities (property.read, event.write, …). See RBAC + roles.