Custom events

Overview

The Formo SDK offers an easy-to-use event collection library that allows you to track custom events in your crypto app. Ensure high quality, structured data with Formo. Start tracking custom events with the Web SDK to get started. Custom events work with Wallet Intelligence and Funnels to give you a complete picture of each user’s journey.

How to track custom events

While Formo autocaptures page views, wallet connects, and transactions, custom events let you track specific actions that matter to your app. This guide shows you how.

When to use custom events

Track actions that aren’t captured automatically:

Action	Why track it
Swap submissions	Measure swap conversion
Deposit completions	Track liquidity flows
Feature usage	Understand adoption
Errors	Debug user issues
Key conversions	Measure business outcomes

Step 1: Import the Formo SDK

Wagmi / React
HTML Snippet

import { useFormo } from '@formo/analytics';

function YourComponent() {
  const analytics = useFormo();

  // Now you can track events
}

The formo object is available globally after the snippet loads:

// Track an event
window.formo.track('Swap Completed', { pair: 'ETH/USDC' });

Step 2: Track a custom event

Use the track function with an event name and optional properties:

analytics.track('Swap Completed', {
  pool_id: 'ETH/USDC',
  amount: 1000,
  slippage: 0.5
});

Event parameters:

Event name (required): Descriptive name for the action
Properties (optional): Key-value pairs with additional context

Step 3: Track with volume, revenue, or points

For events with monetary value, use special properties:

analytics.track('Swap Completed', {
  pair: 'ETH/USDC',
  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
});

These values appear in your dashboard metrics and can be used for:

Revenue attribution by traffic source
Volume tracking per user
Points/rewards leaderboards

Step 4: View custom events

After tracking events:

Go to Activity in the Formo Dashboard
Filter by your custom event name
See all event occurrences

Custom events also appear in:

Wallet Profiles: user’s activity history
Funnels: as conversion steps
Charts: query with SQL

Best practices

Naming conventions:

Good	Bad
`Swap Completed`	`swap`
`Position Opened`	`click`
`Referral Shared`	`event1`

Use descriptive, past-tense names that describe what happened. Properties to include:

// Good: specific, useful properties
analytics.track('Position Opened', {
  pool_id: 'LINK/ETH',
  amount: 1200,
  leverage: '2x',
  source: 'dashboard'  // Where the action originated
});

// Bad: vague or missing properties
analytics.track('Position Opened', {
  data: 'some data'
});

When to track:

Track at the moment the action completes (not when a button is clicked)
For async actions, track on success (and optionally on failure)

Example: Tracking a swap flow

Track multiple events throughout a user flow:

// User clicks swap button
analytics.track('Swap Started', {
  pair: 'ETH/USDC',
  amount_in: 1,
  amount_out_estimate: 3000
});

// User approves token (if needed)
analytics.track('Token Approved', {
  token: 'ETH',
  spender: '0x...'
});

// Swap completes successfully
analytics.track('Swap Completed', {
  pair: 'ETH/USDC',
  amount_in: 1,
  amount_out: 2998,
  volume: 2998,
  slippage: 0.07
});

// Or if swap fails
analytics.track('Swap Failed', {
  pair: 'ETH/USDC',
  error: 'Insufficient liquidity',
  error_code: 'INSUFF_LIQ'
});

Example: Tracking DeFi feature adoption

Measure which protocol features users engage with:

// User opens a liquidity pool
analytics.track('Pool Opened', {
  pool_id: 'ETH/USDC',
  source: 'sidebar'
});

// User completes a key action in the pool
analytics.track('Liquidity Added', {
  pool_id: 'ETH/USDC',
  token_0: 'ETH',
  token_1: 'USDC'
});

Using custom events in funnels

Custom events can be funnel steps:

Go to Funnels > Create Funnel
Add a step with Event type: Custom
Select your custom event name
Optionally add property filters

Example funnel:

Step	Event
1	`page` (visit /swap)
2	`connect`
3	`Swap Started` (custom)
4	`Swap Completed` (custom)

Next Steps

Events API Reference

Full track() API documentation

Funnels

Use custom events in conversion funnels

Charts

Query custom events with SQL

Web SDK

Complete SDK documentation

Getting started

Features

Overview

How to track custom events

When to use custom events

Step 1: Import the Formo SDK

Step 2: Track a custom event

Step 3: Track with volume, revenue, or points

Step 4: View custom events

Best practices

Example: Tracking a swap flow

Example: Tracking DeFi feature adoption

Using custom events in funnels

Next Steps

Events API Reference

Funnels

Charts

Web SDK

​Overview

​How to track custom events

​When to use custom events

​Step 1: Import the Formo SDK

​Step 2: Track a custom event

​Step 3: Track with volume, revenue, or points

​Step 4: View custom events

​Best practices

​Example: Tracking a swap flow

​Example: Tracking DeFi feature adoption

​Using custom events in funnels

​Next Steps

Events API Reference

Funnels

Charts

Web SDK

Overview

How to track custom events

When to use custom events

Step 1: Import the Formo SDK

Step 2: Track a custom event

Step 3: Track with volume, revenue, or points

Step 4: View custom events

Best practices

Example: Tracking a swap flow

Example: Tracking DeFi feature adoption

Using custom events in funnels

Next Steps