Skip to content

Commit 4dfccf5

Browse files
yosriadyclaude
yosriady
and
claude
authored
docs: add per-event Properties sections and align event docs with SDK (#82)
* docs: add per-event Properties sections and align event docs with SDK - Add a `## Properties` table to each event page (page, identify, detect, connect, disconnect, chain, signature) derived from the SDK's EventFactory - Merge page.mdx's `## Fields` + `## Properties` into a single `## Properties` section with per-SDK source columns - Move `address`/`user_id` to the top level in sample payloads to match the SDK (they are common fields, not properties) - Correct transaction `status` enum (add `reverted`) and signature prose (drop the nonexistent "signature hash") - Note that decoded `function_args` are flattened into top-level properties - Remove the `## Fields` section from track.mdx - Rename overview "API call" column to "Event type" and retitle the page to "Events overview" Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: refresh track event page as "Custom events" - Retitle to "Custom events" and update the description/intro - Add a minimal custom-event JSON example in the Properties section - Move the revenue tracking image to after the reserved-properties table Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 4c0c9eb commit 4dfccf5

10 files changed

Lines changed: 91 additions & 61 deletions

File tree

‎data/events/chain.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,19 @@ description: 'Reference for the chain event emitted when a user switches blockch
66
The `chain` event is emitted whenever the user's chain network changes.
77
It includes the chain ID the user switched to.
88

9+
## Properties
10+
11+
| Property | Type | Description |
12+
|:---------|:-----|:------------|
13+
| `chain_id` | Number | Chain ID of the network the user switched to. |
14+
915
## Sample Payload
1016

1117
Here’s the payload of a typical call with most common fields removed:
1218

1319
```json
1420
{
15-
"type": "chain",
21+
"type": "chain",
1622
"address": "0x8e6ca77a7e044ba836a97beb796c124ca3a6a154",
1723
"properties": {
1824
"chain_id": 1

‎data/events/connect.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ description: 'Reference for the connect event emitted when a user connects their
66
The `connect` event is emitted whenever the user connects a wallet.
77
It includes the newly connected chain ID and wallet address of the user.
88

9+
## Properties
10+
11+
| Property | Type | Description |
12+
|:---------|:-----|:------------|
13+
| `chain_id` | Number | Chain ID of the network the wallet connected to. |
14+
915
## Sample Payload
1016

1117
Here’s the payload of a typical call with most common fields removed:
@@ -16,6 +22,6 @@ Here’s the payload of a typical call with most common fields removed:
1622
"address": "0x8e6ca77a7e044ba836a97beb796c124ca3a6a154",
1723
"properties": {
1824
"chain_id": 1
19-
}
25+
}
2026
}
2127
```

‎data/events/detect.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,13 @@ description: "Reference for the detect event that identifies a visitor's install
55

66
The `detect` event lets you identify a visitor's wallet name and rdns.
77

8+
## Properties
9+
10+
| Property | Type | Description |
11+
|:---------|:-----|:------------|
12+
| `provider_name` | String | Name of the detected wallet provider (e.g., MetaMask). |
13+
| `rdns` | String | Reverse-DNS identifier of the wallet provider (e.g., `io.metamask`). |
14+
815
## Sample Payload
916

1017
Here’s the payload of a typical call with most common fields removed:

‎data/events/disconnect.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,19 @@ description: 'Reference for the disconnect event emitted when a user disconnects
66
The `disconnect` event is emitted whenever the user disconnects a wallet.
77
It includes the disconnected chain ID and wallet address of the user.
88

9+
## Properties
10+
11+
| Property | Type | Description |
12+
|:---------|:-----|:------------|
13+
| `chain_id` | Number | Chain ID of the network the wallet disconnected from. |
14+
915
## Sample Payload
1016

1117
Here’s the payload of a typical call with most common fields removed:
1218

1319
```json
1420
{
15-
"type": "disconnect",
21+
"type": "disconnect",
1622
"address": "0x8e6ca77a7e044ba836a97beb796c124ca3a6a154",
1723
"properties": {
1824
"chain_id": 1

‎data/events/identify.mdx‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,20 @@ description: 'Reference for the identify event that ties users to their actions
66
The `identify` event lets you tie a user to their actions and record traits about them.
77
It includes a unique User ID, wallet name, and wallet rdns.
88

9+
## Properties
10+
11+
| Property | Type | Description |
12+
|:---------|:-----|:------------|
13+
| `provider_name` | String | Name of the wallet provider (e.g., MetaMask). |
14+
| `rdns` | String | Reverse-DNS identifier of the wallet provider (e.g., `io.metamask`). |
15+
916
## Sample Payload
1017

1118
Here’s the payload of a typical call with most common fields removed:
1219

1320
```json
1421
{
15-
"type": "identify",
22+
"type": "identify",
1623
"user_id": "0c93652b-a366-4c92-ab87-0c0ab4fba5aa",
1724
"address": "0x9798d87366bdfc5d70b300abdffc4f9e95369b3d",
1825
"properties": {

‎data/events/overview.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
2-
title: 'Event spec overview'
2+
title: 'Events overview'
33
description: "Learn how to send event data to Formo's APIs and the correct format for capturing events with SDKs, including identify, track, connect, and transaction calls."
44
---
55

66
## Events API
77

88
The Events API supports the following event types, each capturing key touchpoints in the user journey:
99

10-
| API call | Description |
11-
| :------- | :---------- |
10+
| Event type | Description |
11+
| :--------- | :---------- |
1212
| [Identify](/data/events/identify) | Identifies a visitor or user |
1313
| [Detect](/data/events/detect) | Identifies a user's wallet provider |
1414
| [Track](/data/events/track) | Records a custom event with arbitrary data |

‎data/events/page.mdx‎

Lines changed: 13 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -7,32 +7,22 @@ The `page` event records whenever a user views a page on your website or a scree
77

88
On web, page properties are automatically collected from the browser. On mobile, the screen name is mapped to page-equivalent fields (`page_title`, `page_path`, `page_url`) so that web and mobile views are processed through the same analytics pipeline.
99

10-
## Fields
11-
12-
Apart from the [common fields](/data/events/common), the `page` call accepts the following properties:
13-
14-
| Property | Type | Description |
15-
|:---------|:-----|:------------|
16-
| `url` | String | Full URL of the page. |
17-
| `path` | String | Path component of the URL (without query string or hash). |
18-
| `hash` | String | Hash fragment of the URL (e.g., `#section`). |
19-
| `query` | String | Query string of the URL (without the leading `?`). |
20-
| `name` | String | Name of the page or screen. |
21-
| `category` | String | Category of the page or screen. |
22-
| `title` | String | Title of the page. |
23-
2410
## Properties
2511

26-
The following table shows which properties are automatically set by each SDK:
12+
| Property | Type | Description | Web SDK | Mobile SDK |
13+
|:---------|:-----|:------------|:--------|:-----------|
14+
| `url` | String | Full URL of the page. | `window.location.href` | Not set |
15+
| `path` | String | Path component of the URL (without query string or hash). | `window.location.pathname` | Not set |
16+
| `hash` | String | Hash fragment of the URL (e.g., `#section`). | `window.location.hash` | Not set |
17+
| `query` | String | Query string of the URL (without the leading `?`). | `window.location.search` | Not set |
18+
| `name` | String | Name of the page or screen. | Caller-provided | Screen name (required) |
19+
| `category` | String | Category of the page or screen. | Caller-provided | Caller-provided |
20+
| `title` | String | Title of the page. | Caller-provided | Not set |
21+
22+
On web, any non-UTM query-string parameters are also added as individual properties. The SDKs additionally auto-collect the following context fields:
2723

28-
| Property | Web SDK | Mobile SDK |
29-
|:---------|:--------|:-----------|
30-
| `properties.url` | `window.location.href` | Not set |
31-
| `properties.path` | `window.location.pathname` | Not set |
32-
| `properties.hash` | `window.location.hash` | Not set |
33-
| `properties.query` | `window.location.search` | Not set |
34-
| `properties.name` | Caller-provided | Screen name (required) |
35-
| `properties.category` | Caller-provided | Caller-provided |
24+
| Context field | Web SDK | Mobile SDK |
25+
|:--------------|:--------|:-----------|
3626
| `context.page_url` | `window.location.href` | `app://{screenName}` |
3727
| `context.page_title` | `document.title` | Screen name |
3828
| `context.page_path` | Not set (derived in backend) | Not set (derived in backend) |

‎data/events/signature.mdx‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,23 @@ description: 'Reference for the signature event that tracks wallet message signi
44
---
55

66
The `signature` event is emitted whenever the user signs a message.
7-
It includes the signature status (requested, rejected, confirmed), message, chain ID, and wallet address.
7+
It includes the signature status (requested, rejected, confirmed), the signed message, chain ID, and wallet address.
8+
9+
## Properties
10+
11+
| Property | Type | Description |
12+
|:---------|:-----|:------------|
13+
| `status` | String | Signature request status: `requested`, `rejected`, or `confirmed`. |
14+
| `chain_id` | Number | Chain ID of the network. |
15+
| `message` | String | The message that was requested to be signed (e.g., a stringified EIP-712 typed-data payload). |
816

917
## Sample Payload
1018

1119
Here’s the payload of a typical call with most common fields removed:
1220

1321
```json
1422
{
15-
"type": "signature",
23+
"type": "signature",
1624
"address": "0x8e6ca77a7e044ba836a97beb796c124ca3a6a154",
1725
"properties": {
1826
"status": "confirmed",

‎data/events/track.mdx‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
title: 'Track event'
3-
description: 'Reference for the Track API call used to record custom user actions like button clicks and purchases, with naming conventions and property schemas.'
2+
title: 'Custom events'
3+
description: 'Reference for the custom events used to record custom user actions and in-app behaviour.'
44
---
55

6-
The Track API call is how you record any [custom events](/features/product-analytics/custom-events) your users are doing,
6+
Record any [custom events](/features/product-analytics/custom-events) in your app,
77
along with properties that describe the action.
88

99
Custom events can capture a broad range of actions, such as clicking a button or completing a purchase.
@@ -20,32 +20,29 @@ When naming events, Formo recommends establishing a consistent naming convention
2020

2121
This allows everyone including you 6 months from now to instantly understand the meaning of an event.
2222

23-
## Fields
24-
25-
Apart from the [common fields](/data/events/common), the `track` call accepts the following fields:
26-
27-
| Field | Type | Required | Description |
28-
|:------|:-----|:---------|:------------|
29-
| `event` | String | ✓ | Name of the user action |
30-
| `properties` | Object | | Includes the properties associated with the event. For more information, check the Properties section below. |
31-
32-
3323
## Properties
3424

3525
Properties are additional information that give more clarity of your users' actions.
3626

27+
Every custom event has `type` set to `track` and `event` set to your custom event name, with the event-specific data passed in the `properties` object:
28+
29+
```json
30+
{
31+
"type": "track",
32+
"event": "Swap Reviewed",
33+
"properties": {
34+
"rating": 5
35+
}
36+
}
37+
```
38+
3739
Formo has reserved some standard properties listed in the following table and handles them in a special manner.
3840

3941
### Tracking volume, revenue, points
4042

4143
You can track `volume`, `revenue`, and `points` in your events.
4244
Once tracked, they are shown on the dashboard.
4345

44-
<Frame caption="Revenue tracking.">
45-
<img src="/images/revenue.png" alt="Revenue tracking." />
46-
</Frame>
47-
48-
4946
Include these optional properties in a custom event to track values associated with an action.
5047

5148
| Property | Type | Description |
@@ -55,6 +52,9 @@ Include these optional properties in a custom event to track values associated w
5552
| `currency` | String | The currency of the revenue as a result of the event, set in ISO 4217 format. If this is not set, Formo assumes the revenue is in USD. |
5653
| `points` | String | An abstract value such as points or XP associated with an event, to be used by various teams. |
5754

55+
<Frame caption="Revenue tracking.">
56+
<img src="/images/revenue.png" alt="Revenue tracking." />
57+
</Frame>
5858

5959
## Sample Payload
6060

‎data/events/transaction.mdx‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,24 @@ description: 'Reference for the transaction event, including status tracking for
44
---
55

66
The `transaction` event is emitted whenever the user performs a transaction.
7-
It includes the transaction status (started, broadcasted, confirmed, reverted, rejected), to address, data, value, transaction hash, chain ID, and wallet address.
7+
It includes the transaction status (started, broadcasted, confirmed, reverted, rejected), recipient address, data, value, transaction hash, chain ID, and wallet address.
88

99
## Properties
1010

1111
| Property | Type | Description |
1212
|----------|------|-------------|
13-
| `status` | string | Transaction status: `started`, `broadcasted`, `confirmed`, `reverted`, or `rejected` |
14-
| `chain_id` | number | Chain ID of the network |
15-
| `data` | string | Transaction calldata (hex-encoded) |
16-
| `to` | string | Recipient address |
17-
| `value` | string | Transaction value (hex-encoded) |
18-
| `transaction_hash` | string | Transaction hash (available after broadcast) |
19-
| `function_name` | string | Decoded function name (if contract interaction) |
20-
| `function_args` | object | Decoded function arguments (if contract interaction) |
21-
| `builder_codes` | string | Comma-separated [builder codes](#builder-codes) extracted from the transaction calldata (ERC-8021) |
13+
| `status` | String | Transaction status: `started`, `broadcasted`, `confirmed`, `reverted`, or `rejected` |
14+
| `chain_id` | Number | Chain ID of the network |
15+
| `data` | String | Transaction calldata (hex-encoded) |
16+
| `to` | String | Recipient address |
17+
| `value` | String | Transaction value (hex-encoded) |
18+
| `transaction_hash` | String | Transaction hash (available after broadcast) |
19+
| `function_name` | String | Decoded function name (if contract interaction) |
20+
| `function_args` | Object | Decoded function arguments (if contract interaction) |
21+
| `builder_codes` | String | Comma-separated [builder codes](#builder-codes) extracted from the transaction calldata (ERC-8021) |
2222

2323
<Note>
24-
Decoded function arguments appear **both** as the nested `function_args` object and flattened into individual top-level properties for easier querying (e.g. `function_args.text` is also emitted as `text`). Nested struct fields are flattened with underscores (e.g. `order.maker` → `order_maker`), and any argument whose name collides with a reserved field is prefixed with `arg_` (e.g. `to` → `arg_to`).
24+
Each entry in `function_args` is also flattened into the event's top-level properties for easier querying. For example, `function_args: { foo: "bar" }` also adds `foo: "bar"` as a property.
2525
</Note>
2626

2727
## Builder Codes

0 commit comments

Comments
 (0)