Web - Formo Docs

The Formo Web SDK is open source and implements the standard Events API.

Installation

Use this pre-built prompt to get started faster: Install Formo with AI.

There are several ways to install the Formo SDK:

Wagmi is recommended for EVM apps with wallet connection
Solana for Solana apps using framework-kit
HTML Snippet is recommended for static websites
React & Next.js (without Wagmi)

We recommend installing Formo on both your website (example.com) and your app (app.example.com) on the same project with the same SDK write key. The standard setup is to use the HTML snippet on your website and Wagmi on your app, with cross-subdomain tracking enabled.

Wagmi

If you’re already using Wagmi, this is the recommended way to install Formo for apps.When wagmi options are provided, the SDK hooks directly into Wagmi’s state management instead of wrapping EIP-1193 providers. This provides:

Native event handling via Wagmi’s built-in state system
Better compatibility with wallet connection libraries (RainbowKit, ConnectKit, etc.)
Full tracking of signatures and transactions via TanStack Query’s mutation cache

Note that transaction and signature autocapture requires the use of wagmi React hooks

Install the Web SDK via NPM.

npm install @formo/analytics --save

// App.tsx

import { WagmiProvider, createConfig, http } from 'wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { FormoAnalyticsProvider } from '@formo/analytics';
import { mainnet } from 'wagmi/chains';

const wagmiConfig = createConfig({
  chains: [mainnet],
  transports: {
    [mainnet.id]: http(),
  },
});

const queryClient = new QueryClient();

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <FormoAnalyticsProvider
          writeKey="<YOUR_WRITE_KEY>"
          options={{
            wagmi: {
              config: wagmiConfig,
              queryClient: queryClient,
            },
          }}
        >
          <YourApp />
        </FormoAnalyticsProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

HTML Snippet

Install this snippet at the <head> of your website:

<script
  src="https://cdn.formo.so/analytics@latest"
  defer onload="window.formofy('<YOUR_WRITE_KEY>');"
></script>

Enable Subresource Integrity (SRI) to improve site security.

React & Next.js (without Wagmi)

Use Wagmi for more reliable and secure event tracking.

Install the Web SDK via NPM.

npm install @formo/analytics --save

// App.tsx (or App.js)

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

const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);

root.render(
  <React.StrictMode>
    <FormoAnalyticsProvider writeKey="<YOUR_WRITE_KEY>">
      <App />
    </FormoAnalyticsProvider>
  </React.StrictMode>
);

// Usage on a page component

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

const HomePage = () => {
  const analytics = useFormo();

  useEffect(() => {
    // Track a custom event
    analytics.track('Swap Completed', { points: 100 });
  }, [analytics]);

  return <div>Welcome to the Home Page!</div>;
};

export default HomePage;

Identify users

Call identify() after a user connects their wallet or signs in on your website or app:

analytics.identify({ address });

OR

window.formo.identify(...);

If no parameters are specified, the Formo SDK will attempt to auto-identify the wallet address.

Wagmi
Privy
HTML Snippet

Call identify() in a useEffect that triggers when the wallet address changes:

import { useFormo } from '@formo/analytics';
import { useAccount } from 'wagmi';
import { useEffect } from 'react';

function App() {
  const { address } = useAccount();
  const analytics = useFormo();

  useEffect(() => {
    if (address && analytics) {
      analytics.identify({ address });
    }
  }, [address, analytics]);
}

The SDK includes parsePrivyProperties() which extracts profile properties (email, social accounts) and all linked wallet addresses from the Privy user object.Call identify() in a useEffect that triggers when the Privy user becomes available:

import { useFormo, parsePrivyProperties } from '@formo/analytics';
import { usePrivy } from '@privy-io/react-auth';
import { useEffect } from 'react';

function App() {
  const { user } = usePrivy();
  const formo = useFormo();

  useEffect(() => {
    if (!user || !formo) return;

    const { properties, wallets } = parsePrivyProperties(user);

    for (const wallet of wallets) {
      formo.identify({ address: wallet.address, userId: user.id }, properties);
    }
  }, [user, formo]);
}

parsePrivyProperties() returns:

properties — a flat object with email, discord, twitter, farcaster, github, telegram, google, apple, and other social identifiers from the Privy user’s linked accounts
wallets — all wallets linked to the Privy user, so each wallet is identified with the same profile properties

<script
  src="https://cdn.formo.so/analytics@latest"
  defer
  onload="
    window.formofy('<YOUR_WRITE_KEY>', {
      ready: function(formo) {
        formo.identify({ address: '0x...' });
      }
    });
  "
></script>

Track events

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.) To track custom events (in-app actions, key conversions) use the track function:

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

const analytics = useFormo();

analytics.track("Position Opened",  // custom event name
  {
    pool_id: "LINK/ETH", // custom event property
    amount: "1200",      // custom event property
    volume: -59.99,      // volume (reserved property, can be positive or negative to track outflows)
    revenue: 99.99,      // revenue (reserved property, must be a non-negative number)
  }
)

OR 

window.formo.track(...)

Using a standardized naming convention for your custom events is recommended. You can track volume, revenue, and points in custom events.

Code examples

Privy

examples/with-privy

Dynamic

examples/with-dynamic

Turnkey

examples/with-turnkey

React

examples/with-react

Next.js (app router)

examples/with-next-app-router

Next.js (pages router)

examples/with-next-page-router

MetaMask SDK

examples/with-metamask

Blocknative

examples/with-web3-onboard

Thirdweb

examples/with-thirdweb

Reown

examples/with-reown

Porto

examples/with-porto

Farcaster Mini App

examples/with-farcaster

Solana

examples/with-solana

React Native

examples/with-react-native

Configuration

Local testing

The SDK skips tracking in localhost by default. To enable tracking locally during development, set tracking to true:

<AnalyticsProvider
    writeKey={WRITE_KEY}
    options={{
        tracking: true, // enable tracking on localhost
    }}
>

Logging

Control the level of logs the SDK prints to the console with the following logLevel settings:

<AnalyticsProvider
    writeKey={WRITE_KEY}
    options={{
        logger: {
            enabled: true,
            levels: ["error", "warn", "info"],
        },
    }}
>

Log Level	Description
trace	Shows the most detailed diagnostic information, useful for tracing program execution flow.
debug	Shows all messages, including function context information for each public method the SDK invokes.
info	Shows informative messages about normal application operation.
warn	Default. Shows error and warning messages.
error	Shows error messages only.

Autocapture

You can configure which wallet events are automatically captured by the SDK:

// Enable full autocapture (default)
const analytics = await FormoAnalytics.init('YOUR_API_KEY', {
  autocapture: true
});

// Disable autocapture for signature and transaction events
const analytics = await FormoAnalytics.init('YOUR_API_KEY', {
  autocapture: {
    connect: true,
    disconnect: true,
    signature: false,    // Disable signature tracking
    transaction: false,  // Disable transaction tracking
    chain: true
  }
});

// Disable all autocapture
const analytics = await FormoAnalytics.init('YOUR_API_KEY', {
  autocapture: false
});

Batching

To support high-performance environments, the SDK sends events in batches.

<AnalyticsProvider
    writeKey={WRITE_KEY}
    options={{
        flushAt: 20, // defaults to batches of 20 events
        flushInterval: 1000 * 60, // defaults to 1 min
    }}
>

Customize this behavior with the flushAt and flushInterval configuration parameters.

Ready callback

The ready callback function executes once the Formo SDK is fully loaded and ready to use. This is useful for performing initialization tasks or calling SDK methods that require the SDK to be ready.

<AnalyticsProvider
    writeKey={WRITE_KEY}
    options={{
        ready: function(formo) {
            // SDK is ready
            console.log('Formo SDK is ready!');            
            formo.identify(); // Auto-identify user
        },
    }}
>

For Browser installations, you can use the ready callback in the onload attribute:

<script
  src="https://cdn.formo.so/analytics@latest"
  defer
  onload="
    window.formofy('<YOUR_WRITE_KEY>', {
      ready: function(formo) {
        formo.identify();
      }
    });
  "
></script>

Environments

You can control tracking behavior in different environments (test, staging) with the tracking option:

// Initialize with a boolean (simple on/off)
const analytics = await FormoAnalytics.init('your-write-key', {
  tracking: true // Enable tracking everywhere, including localhost
});

// Initialize only on production environment
const analytics = await FormoAnalytics.init('your-write-key', {
  tracking: ENV === 'production'
});

// Initialize with an object for exclusion rules
const analytics = await FormoAnalytics.init('your-write-key', {
  tracking: {
    excludeHosts: ['stage-v2.puri.fi'], // Exclude tracking based on window.location.hostname
    excludePaths: ['/test', '/debug'], // Exclude tracking based on window.location.pathname
    excludeChains: [5] // Exclude tracking on Goerli testnet (5)
  }
});

Specify exact hostnames and exact paths in exclusion lists. The Formo Web SDK includes simplified consent management functionality to help you comply with privacy regulations like GDPR, CCPA, and ePrivacy Directive. Control user tracking preferences with simple opt-out and opt-in methods:

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

const analytics = useFormo();

// Check if user has opted out of tracking
console.log(analytics.hasOptedOutTracking())

// If user has not opted out, tracking is enabled
analytics.track('page_view');

// Opt out of tracking (stops all tracking for the user)
analytics.optOutTracking();

// Opt back into tracking (re-enables tracking for the user)
analytics.optInTracking();

For browser installations:

// Manage consent
window.formo.optOutTracking();
window.formo.optInTracking();

Cross subdomain tracking

By default, Formo sets identity cookies on the root domain, sharing visitor identity across all subdomains. This ensures accurate visitor counts and consistent attribution across your subdomains out of the box.

Value	Behavior
`true` (default)	Cookies are set on the root domain (e.g. `.example.com`), sharing visitor identity across all subdomains.
`false`	Cookies are scoped to the current hostname only. A cookie set on `app.example.com` is not visible from `www.example.com`.

With the default crossSubdomainCookies setting:

Cross subdomain tracking: track users as they move between your marketing site, app, docs, and other subdomains.
Accurate attribution: attribute conversions to the correct channel, even when users cross subdomains.
Automatic migration: the SDK migrates existing host-scoped cookies to the apex domain so visitors are not double-counted.

To disable cross-subdomain tracking and scope cookies to the current hostname only, set crossSubdomainCookies to false:

HTML Snippet
React / Next.js
JavaScript

<script
  src="https://cdn.formo.so/analytics@latest"
  defer onload="window.formofy('WRITE_KEY', { crossSubdomainCookies: false });"
></script>

<FormoAnalyticsProvider
  writeKey="WRITE_KEY"
  options={{
    crossSubdomainCookies: false
  }}
>

const analytics = await FormoAnalytics.init('YOUR_API_KEY', {
  crossSubdomainCookies: false
});

Wagmi integration

For apps using Wagmi, enable native integration by providing the Wagmi config and QueryClient:

<FormoAnalyticsProvider
  writeKey="<YOUR_WRITE_KEY>"
  options={{
    wagmi: {
      config: wagmiConfig,      // Required: Wagmi config from createConfig()
      queryClient: queryClient, // Recommended: For signature/transaction tracking
    },
  }}
>

Transaction and signature autocapture requires the use of wagmi React hooks (useWriteContract, useSendTransaction, useSignMessage). Calls via @wagmi/core or viem directly bypass the mutation cache and won’t be tracked. If you are not using these hooks, use the non-wagmi React or Next.js installation methods instead.

When Wagmi mode is enabled, the SDK:

Hooks directly into Wagmi’s state management for connection events
Uses TanStack Query’s mutation cache for signature and transaction tracking
Skips EIP-1193 provider wrapping (no proxy behavior)

Event Type	Without QueryClient	With QueryClient
Connect	✅ Tracked	✅ Tracked
Disconnect	✅ Tracked	✅ Tracked
Chain Change	✅ Tracked	✅ Tracked
Signatures	❌ Not tracked	✅ Tracked
Transactions	❌ Not tracked	✅ Tracked

Use the same QueryClient instance for both Wagmi and Formo to avoid creating multiple cache instances.

Solana integration

The Formo Web SDK supports Solana via framework-kit (@solana/client + @solana/react-hooks). The SDK subscribes to framework-kit’s zustand store as a read-only observer — it never wraps or intercepts wallet methods. See the full Solana example app for a working implementation.

npm install @formo/analytics @solana/client @solana/react-hooks

React (Recommended)
Without React

Wrap your app with FormoAnalyticsProvider and pass client.store in the solana options. The SDK automatically tracks wallet connects, disconnects, account switches, and network changes.

import { createClient, autoDiscover } from '@solana/client';
import { SolanaProvider } from '@solana/react-hooks';
import { FormoAnalyticsProvider } from '@formo/analytics';

const client = createClient({
  cluster: 'devnet',
  walletConnectors: autoDiscover(),
});

function App() {
  return (
    <SolanaProvider client={client}>
      <FormoAnalyticsProvider
        writeKey="<YOUR_WRITE_KEY>"
        options={{
          evm: false, // Optional: disable EVM tracking for Solana-only apps
          solana: {
            store: client.store,
          },
        }}
      >
        <YourApp />
      </FormoAnalyticsProvider>
    </SolanaProvider>
  );
}

Then use the useFormo hook in any component:

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

function MyComponent() {
  const formo = useFormo();

  const handleClick = () => {
    formo.track('button_click', { page: 'home' });
  };
}

If you’re not using React or need manual control, call FormoAnalytics.init() directly:

import { createClient, autoDiscover } from '@solana/client';
import { FormoAnalytics } from '@formo/analytics';

const client = createClient({
  cluster: 'devnet',
  walletConnectors: autoDiscover(),
});

const formo = await FormoAnalytics.init('<YOUR_WRITE_KEY>', {
  evm: false,
  solana: {
    store: client.store,
  },
});

Autocaptured events (via store subscription):

Event	Trigger
Connect	Wallet connects via `useWalletConnection().connect()`
Disconnect	Wallet disconnects
Chain change	Cluster/network switches via `setCluster()`

Manual tracking — framework-kit’s React hooks (useSolTransfer, useSendTransaction, useTransactionPool) manage transaction state locally and don’t write to the store. Transaction and signature events must be tracked explicitly:

import { useFormo, TransactionStatus, SignatureStatus, SOLANA_CHAIN_IDS } from '@formo/analytics';

const formo = useFormo();

// Transactions
formo.transaction({ status: TransactionStatus.STARTED, chainId: SOLANA_CHAIN_IDS['devnet'], address });
const sig = await solTransfer.send({ destination, amount });
formo.transaction({ status: TransactionStatus.CONFIRMED, chainId: SOLANA_CHAIN_IDS['devnet'], address, transactionHash: sig });

// Signatures (signMessage / signTransaction)
formo.signature({ status: SignatureStatus.REQUESTED, chainId: SOLANA_CHAIN_IDS['devnet'], address, message });
const result = await session.signMessage(encoded);
formo.signature({ status: SignatureStatus.CONFIRMED, chainId: SOLANA_CHAIN_IDS['devnet'], address, message, signatureHash });

For Solana-only apps, set evm: false to disable EVM provider detection (EIP-1193 / EIP-6963). This prevents unnecessary tracking of injected EVM wallets like MetaMask.

Referrals

Formo autodetects ref, referral, and refcode query parameters in the URL. You can customize how referrals are detected by the SDK:

const analytics = await FormoAnalytics.init('YOUR_API_KEY', {
  referral: {
    queryParams: ['via', 'ref'],
    pathPattern: '/referral/([^/]+)'
  }
});

In the above configuration, Formo will detect referrals from:

the via and ref query parameters in the URL, and
from the /referral/([^/]+) path pattern

FAQ

What is the difference between the Wagmi integration and the standard React integration?

The Wagmi integration automatically tracks wallet connections, disconnections, chain switches, transactions, and signatures by hooking into Wagmi’s wallet adapter. The standard React integration 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.

How do I track custom events like swaps, deposits, or mints?

Use formo.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 feed and can be queried in the Explorer.

Does the Formo SDK support consent management for GDPR?

Can I use Formo with Privy or other embedded wallet providers?

Yes. The SDK includes a dedicated Privy integration with parsePrivyProperties() to extract profile properties and linked wallet addresses. For other wallet providers, use the standard React integration. If your wallet provider uses Wagmi under the hood (many do, including Privy), you can also use the Wagmi integration for automatic wallet event tracking.

Proxy

To avoid ad-blockers from blocking your requests, we recommend setting up a reverse proxy.

Here are the domains used by Formo to load the SDK and send data:

Domain	Use case
cdn.formo.so	Loads the SDK (only for Website installation) e.g. `https://cdn.formo.so/[email protected]`
events.formo.so	Receives data from the SDK (`http://events.formo.so/v0/raw_events`)

CDN

Some ad blockers block specific SDK-related downloads and API calls based on the domain name and URL. To circumvent this issue you can download and serve the Formo SDK from cdn.formo.so to your own domain e.g. yourdomain.com/formo.js.

Next.js rewrites

If you are using Next.js, you can take advantage of rewrites to behave like a reverse proxy. To do so, add a rewrites() function to your next.config.js file:

// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: "/formo.js",
        destination: "https://cdn.formo.so/[email protected]", // If using website install script
      },
      {
        source: "/api/ingest",
        destination: "https://events.formo.so/v0/raw_events",
      },
    ];
  },
};

Then, replace the website install script to:

<script
    src="https://yourdomain.com/formo.js"
  ...
></script>

Then, configure the Formo SDK to send requests via your rewrite. Update the apiHost parameter in the Formo SDK:

<AnalyticsProvider
  writeKey={WRITE_KEY}
  options={{
    apiHost: "/api/ingest",
  }}
>

See an example Next.js app here.

Next.js middleware

If you are using Next.js and rewrites aren’t working for you, you can write custom middleware to proxy requests to Formo. Create a file named middleware.js/ts in your base directory (same level as the app folder).

import { NextResponse } from "next/server";

export function middleware(request: any) {
  const hostname = "events.formo.so";

  const requestHeaders = new Headers(request.headers);
  requestHeaders.set("host", hostname);

  let url = request.nextUrl.clone();
  url.protocol = "https";
  url.hostname = hostname;
  url.port = 443;
  url.pathname = url.pathname.replace(/^\/ingest/, "");

  return NextResponse.rewrite(url, {
    headers: requestHeaders,
  });
}

export const config = {
  matcher: "/ingest/:path*",
};

In this file, set up code to match requests to a custom route, set a new host header, change the URL to point to Formo, and rewrite the response. Once done, configure the Formo SDK to send requests via your rewrite:

<AnalyticsProvider
  writeKey={WRITE_KEY}
  options={{
    apiHost: "https://your-host-url.com/ingest",
  }}
>

Others

Alternatively, you can set up your own proxy (with Cloudfront, Cloudflare, etc) and pass the URL as the SDK apiHost:

<script
  src="https://cdn.formo.so/analytics@latest"
  defer
  onload="
    window.formofy('<YOUR_WRITE_KEY>', {
      apiHost: 'https://your-host-url.com/ingest',
      ready: function(formo) {
        formo.identify();
      }
    });
  "
></script>

Verification

To verify the proxy is working:

Visit your website / app
Open the network tab in your browser’s developer tools
Check that analytics requests are going through your domain instead of events.formo.so
Check that events show up in the Activity page on the Formo dashboard

SDK

​Installation

​Wagmi

​HTML Snippet

​React & Next.js (without Wagmi)

​Identify users

​Track events

​Code examples

Privy

Dynamic

Turnkey

React

Next.js (app router)

Next.js (pages router)

MetaMask SDK

Blocknative

Thirdweb

Reown

Porto

Farcaster Mini App

Solana

React Native

​Configuration

​Local testing

​Logging

​Autocapture

​Batching

​Ready callback

​Environments

​Consent management

​Cross subdomain tracking

​Wagmi integration

​Solana integration

​Referrals

​FAQ

​Proxy

​CDN

​Next.js rewrites

​Next.js middleware

​Others

​Verification

Installation

Wagmi

HTML Snippet

React & Next.js (without Wagmi)

Identify users

Track events

Code examples

Configuration

Local testing

Logging

Autocapture

Batching

Ready callback

Environments

Consent management

Cross subdomain tracking

Wagmi integration

Solana integration

Referrals

FAQ

Proxy

CDN

Next.js rewrites

Next.js middleware

Others

Verification