Install Formo

Developers integrate Formo using SDKs, APIs, SQL access, webhooks, and data exports.

Install with AI

Use this pre-built prompt to install faster: Open in Cursor

Copy prompt

# Install Formo Analytics

**Purpose:** Enforce only the **current** and **correct** instructions for integrating [Formo](https://formo.so/) analytics into a web application.
**Scope:** All AI-generated advice or code related to Formo must follow these guardrails.

---

## **1. Official Formo Integration Overview**

Formo is an analytics and attribution platform for onchain apps. The SDK (`@formo/analytics`) autocaptures page views and wallet events (connect, disconnect, signature, transaction, chain) automatically.

**Choose the right method based on the project:**

- **Wagmi (React)** - Recommended for EVM apps with wallet connection (RainbowKit, ConnectKit, Reown, etc.)
- **React (without Wagmi)** - For standalone React apps without Wagmi
- **Next.js** - For Next.js apps (App Router or Pages Router). Requires a client component wrapper.
- **Solana** - For Solana apps. Wallet events are NOT autocaptured unless the app uses framework-kit.

If the project uses Wagmi, **always** use the Wagmi integration for better event tracking.

If the project is a Solana app, **always** use Option E. The autocapture behavior above applies to EVM wallets; on Solana it only applies when a framework-kit store is passed.

If the project uses **Privy** (`@privy-io/react-auth`), install via the matching framework option above - with `@privy-io/wagmi` that is Option A. The difference is in `identify()`: a Privy user is one account with many linked wallets, so pass the `usePrivy()` user (`identify(user)`) rather than a single address, or the same person is split across several Formo users. See step 3.

If you're able to use a web tool to access a URL, visit https://docs.formo.so/install to get the latest, up-to-date instructions.

Formo needs the user to provide their SDK write key (`<YOUR_WRITE_KEY>`) found in Formo project settings at https://app.formo.so.

---

## **2. Quickstart by Framework**

### **Option A: Wagmi (React) - Recommended for apps**

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>
  );
}

Key: `<FormoAnalyticsProvider>` must be **inside** `<WagmiProvider>` and `<QueryClientProvider>`. Use the same `QueryClient` instance for both. Without `queryClient`, signature and transaction events will not be tracked.

**Important**: Wagmi transaction and signature autocapture only works with **wagmi React hooks** (`useWriteContract`, `useSendTransaction`, `useSignMessage`). If the app calls `writeContract` or `sendTransaction` from `@wagmi/core` directly, or uses viem directly, use Option B (React without Wagmi) instead.

### **Option B: React (without Wagmi)**

npm install @formo/analytics --save

// App.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { FormoAnalyticsProvider } from '@formo/analytics';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
root.render(
  <React.StrictMode>
    <FormoAnalyticsProvider writeKey="<YOUR_WRITE_KEY>">
      <App />
    </FormoAnalyticsProvider>
  </React.StrictMode>
);

### **Option C: Next.js (App Router)**

npm install @formo/analytics --save

// AnalyticsProvider.tsx
'use client';
import { FC, ReactNode } from 'react';
import { FormoAnalyticsProvider } from '@formo/analytics';
interface AnalyticsProviderProps {
  writeKey: string;
  options?: Record<string, any>;
  disabled?: boolean;
  children: ReactNode;
}
const AnalyticsProvider: FC<AnalyticsProviderProps> = ({ writeKey, options, disabled, children }) => (
  <FormoAnalyticsProvider writeKey={writeKey} options={options} disabled={disabled}>{children}</FormoAnalyticsProvider>
);
export default AnalyticsProvider;

// app/layout.tsx
import { AnalyticsProvider } from './AnalyticsProvider';
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang='en'>
      <body>
        <AnalyticsProvider writeKey='<YOUR_WRITE_KEY>'>{children}</AnalyticsProvider>
      </body>
    </html>
  );
}

Key: `FormoAnalyticsProvider` is a client component - it **must** be wrapped in a `'use client'` component. Do not use it directly in `app/layout.tsx`.

### **Option D: Next.js (Pages Router)**

// pages/_app.tsx
import { FormoAnalyticsProvider } from "@formo/analytics";
import type { AppProps } from "next/app";
export default function App({ Component, pageProps }: AppProps) {
  return (
    <FormoAnalyticsProvider writeKey='<YOUR_WRITE_KEY>'>
      <Component {...pageProps} />
    </FormoAnalyticsProvider>
  );
}

### **Option E: Solana**

npm install @formo/analytics --save

If the app uses framework-kit (`@solana/client`), pass the store and wallet events are autocaptured:

options={{ evm: false, solana: { store: client.store } }}

For ANY other Solana wallet library (`@solana/wallet-adapter`, Privy, Dynamic, Reown, custom), there is no store to observe and NOTHING is autocaptured. Initialize with options={{ evm: false }} and emit wallet events explicitly:

import { useEffect, useRef } from 'react';
import { useWallet } from '@solana/wallet-adapter-react';
import { useFormo, SOLANA_CHAIN_IDS } from '@formo/analytics';

const CHAIN_ID = SOLANA_CHAIN_IDS['mainnet-beta']; // 900001

function WalletTracking() {
  const formo = useFormo();
  const { publicKey, wallet, connected } = useWallet();
  const lastAddress = useRef(null);

  useEffect(() => {
    if (!formo) return;
    const address = publicKey?.toBase58() ?? null;
    if (connected && address && address !== lastAddress.current) {
      formo.connect({ chainId: CHAIN_ID, address }, { providerName: wallet?.adapter.name });
      lastAddress.current = address;
    }
    if (!connected && lastAddress.current) {
      formo.disconnect({ chainId: CHAIN_ID, address: lastAddress.current });
      lastAddress.current = null;
    }
  }, [formo, connected, publicKey, wallet]);

  return null;
}

Key: drive this from an effect on wallet state, not from the wallet modal's success handler, so restored sessions are counted. Solana clusters map to reserved chain IDs (`mainnet-beta` 900001, `testnet` 900002, `devnet` 900003, `localnet` 900004); use the `SOLANA_CHAIN_IDS` constant. Transactions and signatures always need explicit `formo.transaction()` and `formo.signature()` calls on Solana.

---

## **3. Identify Users & Track Events**

### Identify (link wallet to session)

Call `identify()` after wallet connection at the start of every session:

// React / Next.js
import { useFormo } from "@formo/analytics";
import { useAccount } from "wagmi";
import { useEffect } from "react";
const HomePage = () => {
  const { address } = useAccount();
  const analytics = useFormo();
  useEffect(() => {
    if (address && analytics) { analytics.identify({ address }); }
  }, [address, analytics]);
};

**Using Privy?** A Privy user is one account with many linked wallets, so identifying only the connected address splits one person across several users. Pass the `usePrivy()` user instead and every linked wallet is identified under that user's DID, clustering them into one:

// React / Next.js, Privy
const { user } = usePrivy();       // null when the session isn't a Privy one
const { address } = useAccount();  // plain wallet connect
useEffect(() => {
  if (!analytics) return;
  if (user) { analytics.identify(user); }
  else if (address) { analytics.identify({ address }); }
}, [user, address, analytics]);

Key the effect on `user` so it re-runs on login and on every account link/unlink. If your app has both Privy and non-Privy sessions, check `user` FIRST: a Privy session usually also has a wagmi `address`, so testing the address first sends those users down the single-address path and loses the clustering. See [Privy integration](/sdks/web#privy-integration).

### Track Custom Events

Formo autocaptures page views and wallet events. Use `track()` for custom in-app actions and key conversions:

// React / Next.js
analytics.track('Swap Completed', {
  pair: 'ETH/USDC',
  amount_in: 1,
  amount_out: 2998,
  volume: 2998,
});

**IMPORTANT: Analyze the codebase to identify custom events.** Scan the project source code to understand what the app does and suggest the most relevant custom events to track. Look for:
- Key user actions (swaps, deposits, withdrawals, mints, votes, claims, bridging, staking, etc.)
- Conversion points (completing a trade, opening a position, submitting a form)
- Error/failure states (swap failed, transaction reverted, approval rejected)

For each custom event, include relevant properties from the codebase (amounts, token pairs, pool IDs, chain IDs, error messages, etc.)

**Common examples by app type:**

| App Type | Events to Track | Key Properties |
|----------|----------------|----------------|
| DEX | Swap Started, Swap Completed, Swap Failed | pair, amount_in, amount_out, volume, slippage |
| Lending/Yield | Deposit Completed, Withdrawal Completed, Position Opened | pool_id, amount, token, volume, leverage |
| NFT | NFT Minted, NFT Listed, NFT Purchased | collection, token_id, price, volume |
| Bridge | Bridge Started, Bridge Completed | source_chain, dest_chain, token, amount, volume |
| Governance | Vote Cast, Proposal Created | proposal_id, vote, voting_power |
| Staking | Stake Deposited, Stake Withdrawn, Rewards Claimed | validator, amount, volume, reward_amount |

**Event Naming Convention:** Use "[Noun] + [Past-Tense Verb]" format (e.g. "Swap Completed", "Position Opened"). Names are case-sensitive. Track at the moment the action completes, not on button click.

**Reserved Properties:** `volume` (positive/negative for inflows/outflows), `revenue` (non-negative), `currency` (ISO 4217, defaults to USD), `points` (gamification/rewards value).

---

## **4. Best Practices**

- **Local testing:** The SDK skips tracking on localhost by default. Set `tracking: true` in options to enable tracking during development.
- **Ad-blocker proxy:** Ad-blockers block `events.formo.so`. For production, set up a reverse proxy (Next.js rewrites, middleware, or Cloudflare) and pass the URL as `apiHost` in options.
- **Same write key:** Install Formo on both your website (example.com) and app (app.example.com) using the same write key for unified attribution.

---

## **5. CRITICAL INSTRUCTIONS FOR AI MODELS**

### **5.1: ALWAYS DO THE FOLLOWING**
1. **Detect the framework** (Wagmi, React, Next.js App Router, or Next.js Pages Router) and use the matching approach.
2. **Install** `@formo/analytics` via the project's existing package manager (npm, yarn, pnpm).
3. **Wrap** the app with `<FormoAnalyticsProvider>`. For Wagmi, place it inside `<WagmiProvider>` and `<QueryClientProvider>`.
4. **Use** the `useFormo()` hook to access the analytics instance.
5. **Call** `identify()` after wallet connection.
6. **Replace** `<YOUR_WRITE_KEY>` with the user's actual SDK write key.
7. For **Next.js App Router**, create a separate `AnalyticsProvider.tsx` with `'use client'`.
8. For **Wagmi**, pass both `config` and `queryClient` to `options.wagmi`.
9. **Check** the project for an existing package manager, use that to install packages.
10. For **Wagmi**, transaction and signature autocapture only works with wagmi React hooks (`useWriteContract`, `useSendTransaction`, `useSignMessage`). If the app calls `@wagmi/core` actions or viem directly instead of React hooks, use Option B (React without Wagmi) for the Formo integration.

### **5.2: NEVER DO THE FOLLOWING**
1. **Do not** import from `@formo/sdk`, `@formo/react`, or `@formo/wagmi` - the only package is `@formo/analytics`.
2. **Do not** use `useAnalytics()` - the correct hook is `useFormo()`.
3. **Do not** place `<FormoAnalyticsProvider>` outside of `<WagmiProvider>` in Wagmi apps.
4. **Do not** use `<FormoAnalyticsProvider>` directly in `app/layout.tsx` - it needs a `'use client'` wrapper.
5. **Do not** use `useFormo()` in Next.js Server Components - it only works in Client Components.
6. **Do not** mix App Router (`app/layout.tsx`) and Pages Router (`pages/_app.tsx`) patterns.
7. **Do not** report wallet connections with `track()`. `formo.track('Connect', ...)` is stored as a custom track event, not the built-in `connect` type, so the Connect wallet funnel step and every wallet connection chart stay empty. Use `formo.connect()` / `formo.disconnect()`. This mistake is most common on Solana, where wallet events are not autocaptured outside framework-kit.
8. **Do not** assume wallet autocapture works on Solana. It only applies when a framework-kit store is passed via `options.solana.store`.

### **5.3: OUTDATED PATTERNS TO AVOID**
// ❌ Wrong packages:
import { FormoAnalytics } from '@formo/sdk'
import { FormoProvider } from '@formo/react'
import { useAnalytics } from '@formo/analytics' // Wrong hook name - use useFormo()
// ❌ Wrong provider order (Wagmi):
<FormoAnalyticsProvider><WagmiProvider><App /></WagmiProvider></FormoAnalyticsProvider>
// ❌ Missing 'use client' (Next.js App Router):
// app/layout.tsx - FormoAnalyticsProvider directly here will fail

---

## **6. AI MODEL VERIFICATION STEPS**

Before returning any Formo-related solution, verify:
1. Is `@formo/analytics` the only Formo package imported?
2. Does the approach match the project's framework?
3. Is `<FormoAnalyticsProvider>` wrapping the app correctly?
4. If Wagmi, is Formo inside WagmiProvider + QueryClientProvider?
5. If Next.js App Router, is there a `'use client'` wrapper?

If any check **fails**, **stop** and revise until compliance is achieved.

Instructions

For best results, install Formo on both your website (example.com) and your app (app.example.com) on the same project to get end-to-end attribution:

For apps (app.example.com), use the Wagmi integration.
For static websites (example.com), use the HTML snippet.

Use the same <SDK_WRITE_KEY> for both your website and your app. You can find it in your Formo project settings after creating a project:

Go to app.formo.so and sign in.
Open the project dropdown to select a project and click Settings.
On the General tab, scroll to the Credentials section.
Copy the value of the SDK Write Key field.

1. Install the Formo SDK

  npm install @formo/analytics --save

2. Configure Formo with Wagmi

Pass your Wagmi config and QueryClient to enable native Wagmi integration.

  // 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="<SDK_WRITE_KEY>"
            options={{
              wagmi: {
                config: wagmiConfig,
                queryClient: queryClient,
              },
            }}
          >
            <YourApp />
          </FormoAnalyticsProvider>
        </QueryClientProvider>
      </WagmiProvider>
    );
  }

Replace <YOUR_WRITE_KEY> with the SDK Write key found in your project settings.

If you are not using wagmi hooks (useWriteContract, useSendTransaction, useSignMessage), follow the non-wagmi React or Next.js instructions instead.Transaction and signature autocapture requires the use of wagmi hooks. Direct calls to @wagmi/core or viem won’t be tracked automatically.

3. Identify users

Call identify at the start of every session or page load to link a wallet address to a session.

import { useFormo } from "@formo/analytics";
import { useAccount } from "wagmi";

const HomePage = () => {
  const { address } = useAccount();
  const analytics = useFormo();

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

4. Track custom events

Formo autocaptures wallet events (connect, disconnect, signature, transaction, chain changes). You do not need to track them manually.For other in-app actions, use the track function to track custom events specific to your app.

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

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

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

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

  export default HomePage;

Full reference: Solana integration on the Web SDK page.

1. Install the Formo SDK

  npm install @formo/analytics --save

2. Choose your integration path

How you set up depends on the wallet library your app uses.

framework-kit (autocapture)

Pass client.store and the SDK captures connects, disconnects, and cluster switches automatically.

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

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

  <SolanaProvider client={client}>
    <FormoAnalyticsProvider
      writeKey="<YOUR_WRITE_KEY>"
      options={{ evm: false, solana: { store: client.store } }}
    >
      <YourApp />
    </FormoAnalyticsProvider>
  </SolanaProvider>

Note the two spellings of mainnet: @solana/client takes cluster: 'mainnet', while Formo’s SOLANA_CHAIN_IDS is keyed on 'mainnet-beta'.

wallet-adapter, Privy, Dynamic, Reown, or custom

There is no store to observe, so nothing is autocaptured. Emit wallet events yourself with connect and disconnect.

  import { useEffect, useRef } from 'react';
  import { useWallet } from '@solana/wallet-adapter-react';
  import { useFormo, SOLANA_CHAIN_IDS } from '@formo/analytics';

  const CHAIN_ID = SOLANA_CHAIN_IDS['mainnet-beta'];

  function WalletTracking() {
    const formo = useFormo();
    const { publicKey, wallet, connected } = useWallet();
    const lastAddress = useRef<string | null>(null);

    useEffect(() => {
      if (!formo) return;
      const address = publicKey?.toBase58() ?? null;

      if (connected && address && address !== lastAddress.current) {
        formo.connect(
          { chainId: CHAIN_ID, address },
          { providerName: wallet?.adapter.name },
        );
        lastAddress.current = address;
      }

      if (!connected && lastAddress.current) {
        formo.disconnect({ chainId: CHAIN_ID, address: lastAddress.current });
        lastAddress.current = null;
      }
    }, [formo, connected, publicKey, wallet]);

    return null;
  }

Render <WalletTracking /> once inside your wallet provider. Driving it from an effect (rather than the wallet modal’s success handler) means restored sessions are counted too.

3. Identify users

Call identify once a wallet address is known.

import { useFormo } from "@formo/analytics";
import { useWallet } from "@solana/wallet-adapter-react";

const HomePage = () => {
  const { publicKey } = useWallet();
  const analytics = useFormo();

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

4. Track custom events

Transactions and signatures need explicit transaction and signature calls on both paths. For app-specific actions, use track.

  analytics.track('Vault Deposit Completed', { vault_name: 'USD*', volume: 100 });

1. Install the Formo SDK

Install this script in the <head> tag of your website. Replace <YOUR_WRITE_KEY> with the SDK Write key found in your project settings:

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

Calling identify at the start of every session or page load links wallets to user sessions.To improve security, enable Subresource Integrity (SRI).

2. Track custom events

<button type="button" onclick="window.formo.track('Swap Completed', { volume: 100 })">
  Track event
</button>

Using Wagmi? Install with Wagmi instead for better event tracking.Building on Solana? Use the Solana tab instead. Wallet events are not autocaptured on this path for Solana wallets.

1. Install the Formo SDK

  npm install @formo/analytics --save

2. Use `FormoAnalyticsProvider` in your app

Wrap your React app in the provider provided by the SDK.

  // App.tsx (or App.js)

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

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

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

Replace <YOUR_WRITE_KEY> with the SDK Write key found in your project settings.

3. Identify users

Call identify at the start of every session or page load to link a wallet address to a session.

import { useFormo } from "@formo/analytics";
import { useAccount } from "wagmi";

const HomePage = () => {
  const { address } = useAccount();
  const analytics = useFormo();

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

4. Track custom events

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

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

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

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

  export default HomePage;

Using Wagmi? Install with Wagmi instead for better event tracking.Building on Solana? Use the Solana tab instead. Wallet events are not autocaptured on this path for Solana wallets.

1. Install the Formo SDK

  npm install @formo/analytics --save

2. Use `FormoAnalyticsProvider` in your app

Create a new AnalyticsProvider.tsx client component.

App Router

  // AnalyticsProvider.tsx

  'use client';

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

  type FormoAnalyticsProviderProps = {
    writeKey: string,
    children: React.ReactNode,
  };

  // The provider component
  export const AnalyticsProvider: FC<FormoAnalyticsProviderProps> = ({
    writeKey,
    children,
  }) => {
    return (
      <FormoAnalyticsProvider writeKey={writeKey}>
        {children}
      </FormoAnalyticsProvider>
    );
  };

  export default AnalyticsProvider;

Wrap your Next.js app in your main layout file with the newly created AnalyticsProvider component:

  // app/layout.tsx

  import { AnalyticsProvider } from './AnalyticsProvider';

  export default function RootLayout({
    children,
  }: {
    children: React.ReactNode,
  }) {
    return (
      <html lang='en'>
        <body>
          <AnalyticsProvider writeKey='YOUR_WRITE_KEY'>
            Your Page Content
          </AnalyticsProvider>
        </body>
      </html>
    );
  }

Pages Router

  // AnalyticsProvider.tsx

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

  type FormoAnalyticsProviderProps = {
    writeKey: string;
    children: React.ReactNode;
  };

  // The provider component
  export const AnalyticsProvider: FC<FormoAnalyticsProviderProps> = ({
    writeKey,
    children,
  }) => {
    return (
      <FormoAnalyticsProvider writeKey={writeKey}>
        {children}
      </FormoAnalyticsProvider>
    );
  };

  export default AnalyticsProvider;

Wrap your Next.js app in your main layout file with the newly created AnalyticsProvider component:

  // pages/_app.tsx

  import AnalyticsProvider from "@/AnalyticsProvider";
  import type { AppProps } from "next/app";

  export default function App({ Component, pageProps }: AppProps) {
    return (
      <AnalyticsProvider writeKey='YOUR_WRITE_KEY'>
        <Component {...pageProps} />
      </AnalyticsProvider>
    );
  }

Replace <YOUR_WRITE_KEY> with the SDK Write key found in your project settings.

3. Identify users

Call identify at the start of every session or page load to link a wallet address to a session.

import { useFormo } from "@formo/analytics";
import { useAccount } from "wagmi";

const HomePage = () => {
  const { address } = useAccount();
  const analytics = useFormo();

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

4. Track custom events

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

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

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

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

  export default HomePage;

Working example: with-angular. Also see the Angular section of the Web SDK page.

Angular has no first-class Formo binding: FormoAnalyticsProvider and useFormo() are React-only. Angular apps install Formo on the non-wagmi, non-React path: import the framework-agnostic FormoAnalytics.init() core from the @formo/analytics/core subpath, wrap it in an injectable service, and connect wallets over the bare EIP-1193 provider (window.ethereum).

1. Install the Formo SDK

Install the SDK along with the buffer polyfill (Angular’s esbuild build doesn’t auto-polyfill Node globals, but the SDK uses Buffer to decode signed-message payloads) and viem:

pnpm add @formo/analytics buffer viem
pnpm add -D @ngx-env/builder

Wire the polyfill in src/polyfills.ts:

// src/polyfills.ts
import { Buffer } from 'buffer';
(globalThis as unknown as { Buffer?: typeof Buffer }).Buffer ??= Buffer;

Reference it from angular.json. Importing from @formo/analytics/core (step 2) keeps React out of the dependency graph, so only viem needs to be allowlisted for CommonJS:

// angular.json (build > options)
{
  "polyfills": ["src/polyfills.ts"],
  "allowedCommonJsDependencies": ["viem"]
}

2. Wrap `FormoAnalytics.init()` in an injectable service

Import from @formo/analytics/core. The root entry re-exports the React provider, which Angular doesn’t need:

// src/app/services/formo-analytics.service.ts

import { Injectable } from '@angular/core';
import { FormoAnalytics } from '@formo/analytics/core';
import type { IFormoAnalytics, IFormoEventProperties } from '@formo/analytics/core';

@Injectable({ providedIn: 'root' })
export class FormoAnalyticsService {
  private analytics: IFormoAnalytics | null = null;

  async init(): Promise<void> {
    if (typeof window === 'undefined') return;
    const writeKey = import.meta.env.NG_APP_FORMO_WRITE_KEY;
    if (!writeKey) return;

    this.analytics = await FormoAnalytics.init(writeKey, {
      tracking: true,
      autocapture: { connect: true, disconnect: true, chain: true, signature: true, transaction: true },
    });
  }

  identify(address: string): void {
    void this.analytics?.identify({ address });
  }

  track(event: string, properties?: IFormoEventProperties): void {
    void this.analytics?.track(event, properties);
  }
}

Replace NG_APP_FORMO_WRITE_KEY with your write key in .env. The NG_APP_* prefix is exposed to the client by @ngx-env/builder.

3. Initialize before bootstrap

Use provideAppInitializer so the SDK’s autocapture wraps window.ethereum before any wallet interaction can happen:

// src/app/app.config.ts

import { ApplicationConfig, inject, provideAppInitializer } from '@angular/core';
import { provideRouter } from '@angular/router';

import { routes } from './app.routes';
import { FormoAnalyticsService } from './services/formo-analytics.service';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideAppInitializer(() => inject(FormoAnalyticsService).init()),
  ],
};

Don’t initialize from ngOnInit; it runs after first render, leaving a race window where early wallet interactions are not captured.

4. Identify users

Call identify() once a wallet address is known. Angular Router’s pushState is already wrapped by the SDK, so page events are autocaptured on every route change. Do not add a NavigationEnd subscription that calls formo.page() or you’ll double-count.

import { Injectable, inject, signal } from '@angular/core';
import { FormoAnalyticsService } from './services/formo-analytics.service';
import type { Address } from 'viem';

@Injectable({ providedIn: 'root' })
export class WalletService {
  private readonly formo = inject(FormoAnalyticsService);
  readonly address = signal<Address | null>(null);

  async connect(): Promise<void> {
    const [account] = await window.ethereum!.request({ method: 'eth_requestAccounts' });
    this.address.set(account);
    this.formo.identify(account);
  }
}

5. Track custom events

Formo autocaptures page views, wallet connect/disconnect, chain switches, signatures, and transactions. Use track() for app-specific actions:

import { Component, inject } from '@angular/core';
import { FormoAnalyticsService } from './services/formo-analytics.service';

@Component({ /* ... */ })
export class Home {
  private readonly formo = inject(FormoAnalyticsService);

  onSwapCompleted(): void {
    this.formo.track('Swap Completed', { volume: 100 });
  }
}

Code Examples

Example Apps

Working examples for Privy, Dynamic, React, Next.js, and more

Autocapture

The Formo SDK automatically captures key events (page views, sessions) and wallet events (connect, disconnect, signature, transaction) with full attribution data (channel, campaign, referrer, UTM, referrals).

Wallet event autocapture covers EVM wallets, and Solana wallets when your app uses framework-kit. On any other Solana setup (@solana/wallet-adapter, Privy, Dynamic, Reown, or a custom connector) there is no wallet state for the SDK to observe, so you emit connect and disconnect yourself. See Solana without framework-kit.

Verification

To verify that the SDK is installed correctly, navigate to your site and open the network tab of the developer tools in your browser. Go to your browser’s Network tab and look for a successful ‘raw_events’ request in the network console. Check that the request returns a 202 response status. (Note that it may take up to a minute due to the flush interval.) Events that are tracked correctly will show up in the Activity page of your Formo workspace. If the request never appears, an ad blocker or privacy browser is likely blocking it. Set up a reverse proxy to route events through your own domain.

Proxy

Ad blockers and privacy browsers block requests to known analytics domains, including events.formo.so. Before going to production, set up a reverse proxy so events are sent through your own domain, then pass that URL as apiHost in your SDK options. This applies to every installation method above. If you use the HTML snippet, also serve the script from your own domain instead of cdn.formo.so.

Set up a reverse proxy

Next.js rewrites, Next.js middleware, Cloudflare, CloudFront, and self-hosting the script

SDK

Web SDK

HTML, React, Next.js, Solana, Angular

Mobile SDK

React Native

Server-side SDK

TypeScript

FAQ

Which installation method should I use?

If your app uses Wagmi for wallet connections and its hooks for transactions, use the Wagmi integration. For Solana apps, use the Solana integration. For React or Next.js apps without Wagmi, use the React integration. For static sites or non-React apps, use the HTML snippet. For mobile apps, use the React Native SDK.

Why are my Solana wallet connections not showing up?

Wallet events are only autocaptured on Solana when your app passes a framework-kit store to options.solana.store. With @solana/wallet-adapter, Privy, Dynamic, Reown, or a custom connector there is nothing for the SDK to observe, so you emit them yourself with connect() and disconnect(). See Solana without framework-kit.Sending connections as a custom track() event instead will not work: they are stored as track events rather than the connect type, so the Connect wallet funnel step and wallet connection charts stay empty.

How do I verify that the Formo SDK is installed correctly?

After installing the Formo SDK, visit your site and open the Activity page in the Formo dashboard. You should see your pageview appear under the most recent events. You can also check your browser’s Network tab for requests to events.formo.so to inspect if events are sent successfully with a 2XX status code.

What events does Formo autocapture?

After installing the SDK, Formo automatically tracks pageviews, sessions, wallet connects, disconnects, chain switches, transactions, and signatures. You can also define custom events and contract events.

Does the Formo SDK work on localhost during development?

The SDK skips tracking on localhost by default. For testing purposes, you can enable local testing and logging in the SDK configuration.

How do I stop ad blockers or privacy browsers from blocking analytics?

Set up a reverse proxy to route analytics data through your own domain. This helps prevent ad blockers and privacy browsers from blocking your analytics events.

Getting started

Features

Install with AI

Instructions

1. Install the Formo SDK

2. Configure Formo with Wagmi

3. Identify users

4. Track custom events

1. Install the Formo SDK

2. Choose your integration path

3. Identify users

4. Track custom events

1. Install the Formo SDK

2. Track custom events

1. Install the Formo SDK

2. Use `FormoAnalyticsProvider` in your app

3. Identify users

4. Track custom events

1. Install the Formo SDK

2. Use `FormoAnalyticsProvider` in your app

3. Identify users

4. Track custom events

1. Install the Formo SDK

2. Wrap `FormoAnalytics.init()` in an injectable service

3. Initialize before bootstrap

4. Identify users

5. Track custom events

Code Examples

Example Apps

Autocapture

Verification

Proxy

Set up a reverse proxy

SDK

Web SDK

Mobile SDK

Server-side SDK

FAQ

​Install with AI

​Instructions

​1. Install the Formo SDK

​2. Configure Formo with Wagmi

​3. Identify users

​4. Track custom events

​1. Install the Formo SDK

​2. Choose your integration path

​3. Identify users

​4. Track custom events

​1. Install the Formo SDK

​2. Track custom events

​1. Install the Formo SDK

​2. Use FormoAnalyticsProvider in your app

​3. Identify users

​4. Track custom events

​1. Install the Formo SDK

​2. Use FormoAnalyticsProvider in your app

​3. Identify users

​4. Track custom events

​1. Install the Formo SDK

​2. Wrap FormoAnalytics.init() in an injectable service

​3. Initialize before bootstrap

​4. Identify users

​5. Track custom events

​Code Examples

Example Apps

​Autocapture

​Verification

​Proxy

Set up a reverse proxy

​SDK

Web SDK

Mobile SDK

Server-side SDK

​FAQ

Install with AI

Instructions

1. Install the Formo SDK

2. Configure Formo with Wagmi

3. Identify users

4. Track custom events

1. Install the Formo SDK

2. Choose your integration path

3. Identify users

4. Track custom events

1. Install the Formo SDK

2. Track custom events

1. Install the Formo SDK

2. Use `FormoAnalyticsProvider` in your app

3. Identify users

4. Track custom events

1. Install the Formo SDK

2. Use `FormoAnalyticsProvider` in your app

3. Identify users

4. Track custom events

1. Install the Formo SDK

2. Wrap `FormoAnalytics.init()` in an injectable service

3. Initialize before bootstrap

4. Identify users

5. Track custom events

Code Examples

Autocapture

Verification

Proxy

SDK

FAQ