Event spec

Origamy speaks the Segment event protocol: five event types, a shared envelope of common fields, and a context object describing where the event came from. Existing Segment or RudderStack instrumentation maps over without changes.

Common fields

Every event carries these fields (the Web SDK fills them all in automatically):

Field	Type	Description
`type`	string	One of `track`, `identify`, `page`, `group`, `alias`.
`messageId`	string	Unique per event; the pipeline’s deduplication key. Reuse it on retries.
`timestamp`	string	ISO-8601 time the event happened.
`anonymousId`	string	Pre-identification visitor ID.
`userId`	string?	Present once the user is identified.
`context`	object	Environment the event was captured in — see below.

`track`

An action the user performed. Name events in Object Action title case — "Order Completed", "Signed Up" — with snake_case property keys.

{
  "type": "track",
  "event": "Order Completed",
  "properties": {
    "order_id": "12345",
    "amount": 99.99,
    "currency": "USD"
  },
  "messageId": "a3f1c9e0-5b2d-4c8a-9e1f-7d6b4a2c8e01",
  "timestamp": "2026-07-02T12:00:00.000Z",
  "anonymousId": "anon-9f2b",
  "userId": "user_123",
  "context": { "...": "..." }
}

`identify`

Who the user is. traits merge into the user’s profile — send only what changed.

{
  "type": "identify",
  "traits": {
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "plan": "premium"
  },
  "messageId": "…",
  "timestamp": "…",
  "anonymousId": "anon-9f2b",
  "userId": "user_123",
  "context": { "...": "..." }
}

`page`

A page view. The Web SDK also mirrors page details into context.page.

{
  "type": "page",
  "name": "Pricing",
  "properties": {
    "url": "https://example.com/pricing",
    "path": "/pricing",
    "title": "Pricing — Example",
    "referrer": "https://google.com"
  },
  "messageId": "…",
  "timestamp": "…",
  "anonymousId": "anon-9f2b",
  "context": { "...": "..." }
}

`group`

Associates the user with an account, company, or team.

{
  "type": "group",
  "groupId": "company_456",
  "traits": {
    "name": "Acme Corp",
    "plan": "enterprise",
    "employees": 100
  },
  "messageId": "…",
  "timestamp": "…",
  "anonymousId": "anon-9f2b",
  "userId": "user_123",
  "context": { "...": "..." }
}

`alias`

Links two identities so identity resolution can merge their history — typically fired at signup to connect the anonymous visitor to the new user ID.

{
  "type": "alias",
  "previousId": "anon-9f2b",
  "userId": "user_123",
  "messageId": "…",
  "timestamp": "…",
  "anonymousId": "anon-9f2b",
  "context": { "...": "..." }
}

The `context` object

Describes the environment the event was captured in. All fields are optional except library; custom keys are allowed.

Field	Description
`library`	`{ name, version }` of the SDK that produced the event.
`page`	`{ path, referrer, search, title, url }` of the page at event time.
`campaign`	Marketing attribution parsed from the URL — see below.
`userAgent`	Browser user-agent string.
`locale`	e.g. `"en-US"`.
`timezone`	e.g. `"Africa/Lagos"`.
`screen`	`{ width, height }` in CSS pixels.

`context.campaign`

Attribution fields parsed from URL parameters at event time, mirroring Segment’s shape so downstream destinations need no mapping. Omitted entirely when no attribution parameters are present.

Field	Source parameter
`source`	`utm_source`
`medium`	`utm_medium`
`name`	`utm_campaign`
`term`	`utm_term`
`content`	`utm_content`
`gclid`	Google Ads click ID
`fbclid`	Meta click ID
`msclkid`	Microsoft Ads click ID
`ttclid`	TikTok click ID

{
  "context": {
    "library": { "name": "origamy-web-sdk", "version": "1.0.0" },
    "page": {
      "path": "/pricing",
      "url": "https://example.com/pricing?utm_source=newsletter",
      "title": "Pricing — Example",
      "referrer": "",
      "search": "?utm_source=newsletter"
    },
    "campaign": { "source": "newsletter", "medium": "email" },
    "userAgent": "Mozilla/5.0 …",
    "locale": "en-US",
    "timezone": "Africa/Lagos",
    "screen": { "width": 1728, "height": 1117 }
  }
}

Event spec

Common fields

track

identify

page

group

alias

The context object

context.campaign