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. See the Web SDK docs to get started.

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.

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

React / Next.js
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 the reserved volume, revenue, and points properties:

analytics.track('Swap Completed', {
  pair: 'ETH/USDC',
  volume: 5000,   // volume of the swap; can be positive or negative
  revenue: 25,    // revenue earned (e.g., fees); must be non-negative
  points: 100     // loyalty/reward points
});

See Tracking volume, revenue, points for the full field reference, including currency (defaults to USD). These values power revenue attribution, volume tracking, and points/rewards leaderboards in your dashboard.

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

Examples

Tracking a swap flow

Track multiple events throughout a user flow:

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

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

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

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

Tracking DeFi feature adoption

Measure which features users engage with:

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

// User completes a key action in the pool
analytics.track('Liquidity Added', {
  pool_id: 'ETH/USDC',
  pool_address: '0x...',
  token_in: 'ETH',
  token_out: 'USDC'
});

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

Examples

Tracking a swap flow

Tracking DeFi feature adoption

​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

​Examples

​Tracking a swap flow

​Tracking DeFi feature adoption

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

Examples

Tracking a swap flow

Tracking DeFi feature adoption