Skip to main content

​
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:
ActionWhy track it
Button clicksMeasure CTA effectiveness
Form submissionsTrack lead generation
Feature usageUnderstand adoption
ErrorsDebug user issues
Key conversionsMeasure business outcomes

​
Step 1: Import the Formo SDK

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

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

  // Now you can track events
}

​
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('Trade Executed', {
  pair: 'ETH/USDC',
  volume: 5000,    // USD value of the trade
  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:
  1. Go to Activity in the Formo Dashboard
  2. Filter by your custom event name
  3. See all event occurrences
Custom events also appear in:

​
Best practices

Naming conventions:
GoodBad
Swap Completedswap
Position Openedclick
Referral Sharedevent1
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 feature adoption

Measure which features users engage with: 
// User opens a feature
analytics.track('Feature Opened', {
  feature: 'Portfolio',
  source: 'sidebar'
});

// User completes key action in feature
analytics.track('Portfolio Export', {
  format: 'csv',
  date_range: '30d'
});

​
Using custom events in funnels

Custom events can be funnel steps:
  1. Go to Funnels > Create Funnel
  2. Add a step with Event type: Custom
  3. Select your custom event name
  4. Optionally add property filters
Example funnel:
StepEvent
1page (visit /swap)
2connect
3Swap Started (custom)
4Swap 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