Align docs examples to DeFi flows: swaps, deposits, mints, and quests (#89)

yosriady · web-flow · commit ec48f14272d3 · 2026-06-23T22:31:47.000+07:00
* docs: use crypto event examples consistently

* Fix typo in web SDK track docs

* Add Vale vocabulary for docs terms

* Update Vale ignores for docs lint
diff --git a/.vale.ini b/.vale.ini
@@ -0,0 +1,8 @@
+StylesPath = styles
+Vocab = Formo
+MinAlertLevel = suggestion
+
+[*.{md,mdx}]
+BasedOnStyles = Vale
+
+TokenIgnores = \b(Wagmi|Solana|Onchain|Autocapture|Autocaptured|Serverless|formo)\b
diff --git a/data/concepts.mdx b/data/concepts.mdx
@@ -36,12 +36,12 @@ Wallets are automatically linked to the user when multiple wallets are connected
 ### 3. Properties
 
 Properties are **additional information about users and events.**
-- Event properties are attributes that describe details specific to the particular instance of an event. For example, if you had a Purchase Completed event, you could specify what the user purchased, the total value of the order, and the payment method used.
+- Event properties are attributes that describe details specific to the particular instance of an event. For example, if you had a Swap Completed event, you could specify the token pair, input amount, output amount, volume, and protocol fee.
 - User properties are traits describing the user and apply across all their future events until the properties are modified. Formo's SDK captures several user properties by default, and you can also set up your own properties to track.
 
 Properties examples:
 - A Connect Wallet event has wallet address and chain ID (Ethereum, Base, etc.) 
 - A Page View event has page URL, referrer URL, and other metadata.
 - A User has net worth and first-touch UTM parameter properties.
 
-When you track custom events, you can also set properties to describe the event. For example, if you had a Purchase Completed event, you could specify what the user purchased, the total value of the order, and the payment method used.
+When you track custom events, you can also set properties to describe the event. For example, if you had a Swap Completed event, you could specify the token pair, input amount, output amount, volume, and protocol fee.
diff --git a/data/events/track.mdx b/data/events/track.mdx
@@ -6,17 +6,17 @@ description: 'Reference for the custom events used to record custom user actions
 Record any [custom events](/features/product-analytics/custom-events) in your app, 
 along with properties that describe the action. 
 
-Custom events can capture a broad range of actions, such as clicking a button or completing a purchase.
+Custom events can capture a broad range of actions, such as starting a swap or completing a deposit.
 
-Additional information about the event can be included in the properties field. For example, for a `Purchase Completed` event, you may want to include the product ids of the purchased products.
+Additional information about the event can be included in the properties field. For example, for a `Swap Completed` event, you may want to include the token pair, input amount, and output amount.
 
 ## Naming events
 
 When naming events, Formo recommends establishing a consistent naming convention that uses:
 
 - Consistent formatting: Event names are case sensitive.
-- A consistent syntax:  Adopt nouns and past tense verbs like `Swap Reviewed` and `Order Submitted`. A standard of `[Noun] + [Past-Tense Verb]` ensures all your events are consistent.
-- A consistent actor: Does `Message Sent` mean that the user sent a message or that you sent a message to the user? If all your events are named in a way that reflects the user's perspective, the meaning is clear immediately.
+- A consistent syntax:  Adopt nouns and past tense verbs like `Swap Completed` and `Deposit Submitted`. A standard of `[Noun] + [Past-Tense Verb]` ensures all your events are consistent.
+- A consistent actor: Does `Transaction Submitted` mean that the user submitted a transaction or that your app submitted it on their behalf? If all your events are named in a way that reflects the user's perspective, the meaning is clear immediately.
 
 This allows everyone including you 6 months from now to instantly understand the meaning of an event.
 
@@ -29,9 +29,11 @@ Every custom event has `type` set to `track` and `event` set to your custom even
 ```json
 {
   "type": "track",
-  "event": "Swap Reviewed",
+  "event": "Swap Completed",
   "properties": {
-    "rating": 5
+    "pair": "ETH/USDC",
+    "token_in": "ETH",
+    "token_out": "USDC"
   }
 }
 ```
@@ -56,20 +58,36 @@ Include these optional properties in a custom event to track values associated w
 	<img src="/images/revenue.png" alt="Revenue tracking." />
 </Frame>
 
+For example, call `.track()` with the reserved properties alongside any other event properties:
+
+```typescript
+analytics.track('Swap Completed', {
+  pair: 'ETH/USDC',
+  token_in: 'ETH',
+  token_out: 'USDC',
+  amount_in: 1.5,
+  amount_out: 4500,
+  volume: 4500,
+  revenue: 13.5,
+  points: 50
+});
+```
+
 ## Sample Payload
 
 ```json
 {
   "type": "track",
-  "event": "Product Reviewed",
+  "event": "Swap Completed",
   "properties": {
-    "volume": -100.5,
-    "revenue": 20.5,
-    "currency": "USD",
-    "points": 100,
-    "product_id" : "9578257311",
-    "rating" : 3.0,
-    "review_body" : "Good value for the price."
+    "pair": "ETH/USDC",
+    "token_in": "ETH",
+    "token_out": "USDC",
+    "amount_in": 1.5,
+    "amount_out": 4500,
+    "volume": 4500,
+    "revenue": 13.5,
+    "points": 50
   }
 }
-```
+```
diff --git a/data/metrics.mdx b/data/metrics.mdx
@@ -35,7 +35,7 @@ How many times a page has been viewed across your site or app.
 
 ### Sessions
 
-A session (also known as a visit) is a set of actions that a user takes on your site. 
+A session (also known as a visit) is a set of actions that a user takes on your site.
 Formo counts unique session IDs. With the web SDK, each visitor's session is counted once per day, so one visitor can have multiple sessions across days.
 
 ### Session Duration
@@ -145,7 +145,7 @@ Users who visit your site or app for the first time within the selected time per
 
 ### Returning Users
 
-Users who have visited your site or app in previous time periods and return within the current period. 
+Users who have visited your site or app in previous time periods and return within the current period.
 
 ### Resurrected Users
 
@@ -163,7 +163,7 @@ Users with no activity within the project's churn window.
 
 Events are user-defined custom events. They have a name and optional metadata key/value pairs. When you expand the activity feed, you can view and filter the metadata.
 
-Metadata can be anything. For example, you can define an event Button clicked and track which button was clicked as the metadata field `button=Header`. 
+Metadata can be anything. For example, you can define a `Swap Completed` event and track the swap pair as the metadata field `pair=ETH/USDC`.
 
 ### Top apps
 
diff --git a/features/product-analytics/custom-events.mdx b/features/product-analytics/custom-events.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Custom events'
-description: 'Define and track custom events like button clicks, form submissions, and purchases with structured properties using the Formo SDK Track API.'
+description: 'Define and track custom events like swaps, deposits, and quests with structured properties using the Formo SDK Track API.'
 ---
 
 ## Overview
@@ -22,8 +22,8 @@ Track actions that aren't captured automatically:
 
 | Action | Why track it |
 |--------|--------------|
-| Button clicks | Measure CTA effectiveness |
-| Form submissions | Track lead generation |
+| Swap submissions | Measure swap conversion |
+| Deposit completions | Track liquidity flows |
 | Feature usage | Understand adoption |
 | Errors | Debug user issues |
 | Key conversions | Measure business outcomes |
@@ -47,7 +47,7 @@ Track actions that aren't captured automatically:
 
     ```javascript
     // Track an event
-    window.formo.track('Event Name', { property: 'value' });
+    window.formo.track('Swap Completed', { pair: 'ETH/USDC' });
     ```
   </Tab>
 </Tabs>
@@ -73,9 +73,11 @@ analytics.track('Swap Completed', {
 For events with monetary value, use special properties:
 
 ```typescript
-analytics.track('Trade Executed', {
+analytics.track('Swap Completed', {
   pair: 'ETH/USDC',
-  volume: 5000,    // USD value of the trade
+  token_in: 'ETH',
+  token_out: 'USDC',
+  volume: 5000,    // USD value of the swap
   revenue: 25,     // Revenue earned (e.g., fees)
   points: 100      // Loyalty/reward points
 });
@@ -167,21 +169,22 @@ analytics.track('Swap Failed', {
 });
 ```
 
-### Example: Tracking feature adoption
+### Example: Tracking DeFi feature adoption
 
-Measure which features users engage with:
+Measure which protocol features users engage with:
 
 ```typescript
-// User opens a feature
-analytics.track('Feature Opened', {
-  feature: 'Portfolio',
+// User opens a liquidity pool
+analytics.track('Pool Opened', {
+  pool_id: 'ETH/USDC',
   source: 'sidebar'
 });
 
-// User completes key action in feature
-analytics.track('Portfolio Export', {
-  format: 'csv',
-  date_range: '30d'
+// User completes a key action in the pool
+analytics.track('Liquidity Added', {
+  pool_id: 'ETH/USDC',
+  token_0: 'ETH',
+  token_1: 'USDC'
 });
 ```
 
diff --git a/sdks/mobile.mdx b/sdks/mobile.mdx
@@ -230,14 +230,14 @@ formo.track('Swap Completed', {
 });
 
 // With reserved properties for analytics
-formo.track('Purchase Completed', {
-  productId: 'premium-nft-001',
+formo.track('NFT Minted', {
+  collection: 'founders-pass',
+  tokenId: '001',
   revenue: 99.99,   // Reserved: revenue tracking
-  currency: 'USD',  // Reserved: currency for revenue
 });
 
-formo.track('Achievement Unlocked', {
-  achievementId: 'first_transaction',
+formo.track('Quest Completed', {
+  questId: 'first_swap',
   points: 500,      // Reserved: points tracking
 });
 
diff --git a/sdks/server.mdx b/sdks/server.mdx
@@ -53,11 +53,15 @@ To track custom events (actions, conversions, or backend states) use the [`track
 await analytics.track({
   address: "0x9798d87366bdfc5d70b300abdffc4f9e95369b3d", // optional: wallet address
   anonymousId: uuid(), // optional: auto-generated if not provided
-  event: "Purchase Completed", // required: event name
+  event: "Swap Completed", // required: event name
   properties: {
-    order_id: "123",
-    revenue: 99.99,
-    currency: "USD",
+    pair: "ETH/USDC",
+    token_in: "ETH",
+    token_out: "USDC",
+    amount_in: 1.5,
+    amount_out: 4500,
+    volume: 4500,
+    revenue: 13.5,
   },
 });
 ```
diff --git a/sdks/web.mdx b/sdks/web.mdx
@@ -326,7 +326,7 @@ If no parameters are specified, the Formo SDK will attempt to auto-identify the
 
 > The Web SDK automatically captures common events such as page views and wallet events (connect, disconnect, signature, transaction, etc) with full attribution (referrer, UTM, referrals.) You do not need to manually track them.
 
-To track custom events (in-app user actions, key conversions) use the [`track`](/data/events/track) function with details of what happenned:
+To track custom events (in-app user actions, key conversions) use the [`track`](/data/events/track) function with details of what happened:
 
 ```ts
 import { useFormo } from '@formo/analytics';
@@ -826,7 +826,7 @@ npm install @formo/analytics @solana/client @solana/react-hooks
       const formo = useFormo();
 
       const handleClick = () => {
-        formo.track('button_click', { page: 'home' });
+        formo.track('Swap Started', { pair: 'ETH/USDC' });
       };
     }
     ```
@@ -894,7 +894,7 @@ For Solana-only apps, set `evm: false` to disable EVM provider detection (EIP-11
     The [Wagmi integration](#wagmi) automatically tracks wallet connects, disconnects, chain switches, transactions, and signatures by hooking into Wagmi's wallet adapter. The standard [React integration](#react--nextjs-without-wagmi) tracks wallet events by wrapping the EIP-1193 wallet provider to track signatures and transactions. Use the Wagmi integration if your dApp uses Wagmi and its hooks.
   </Accordion>
   <Accordion title="How do I track custom events like swaps, deposits, or mints?">
-    Use [formo.track()](/data/events/track) to send custom events with any properties you need. For example: `formo.track('swap', { tokenIn: 'USDC', tokenOut: 'ETH', amount: 1000 })`. Custom events appear in the [Activity](/features/product-analytics/activity) feed and can be queried in the [Explorer](/features/product-analytics/explore).
+    Use [formo.track()](/data/events/track) to send custom events with any properties you need. For example: `formo.track('Swap Completed', { pair: 'ETH/USDC', token_in: 'ETH', token_out: 'USDC', amount_in: 1.5 })`. Custom events appear in the [Activity](/features/product-analytics/activity) feed and can be queried in the [Explorer](/features/product-analytics/explore).
   </Accordion>
   <Accordion title="Does the Formo SDK support consent management for GDPR?">
     Yes. The SDK provides built-in [consent management](#consent-management) with `optOutTracking()` and `optInTracking()` methods. Call `optOutTracking()` to stop all tracking for a user, and `optInTracking()` to re-enable it. Formo does not use third-party cookies, IP addresses, or device fingerprinting, so most jurisdictions do not require a cookie consent banner.
diff --git a/styles/config/vocabularies/Formo/accept.txt b/styles/config/vocabularies/Formo/accept.txt
@@ -0,0 +1,68 @@
+Angular's
+Autocapture
+Autocaptured
+Beehiiv
+Bing
+Cloudfront
+Dailymotion
+Ethereum
+Farcaster
+Formo
+Formo's
+Genspark
+Kagi
+Kimi
+Naver
+OAuth
+Onchain
+Phind
+Pinterest
+Qwen
+SDK's
+SDKs
+Serverless
+Snapchat
+Solana
+Subresource
+Substack
+UTMs
+Uniswap
+Vercel
+Wagmi
+Wagmi's
+Wistia
+Yandex
+async
+autocapture
+autocaptured
+autocaptures
+autodetects
+backgrounding
+config
+crypto
+dApp
+dApps
+denylist
+ePrivacy
+enqueued
+esbuild
+formo
+globals
+hostname
+hostnames
+injectable
+leaderboards
+lightbulb
+logLevel
+middleware
+offchain
+onchain
+pageview
+polyfill
+serverless
+solana
+subpath
+summer_sale
+viem
+wagmi
+zustand
