⭐SDK Setup & Installation

The Fuul Web SDK gives you access to all the functions needed to integrate Fuul into your website — tracking referrals, displaying leaderboards, managing affiliate codes, claiming rewards, and more.

This guide assumes you have already created a Fuul account and generated an API key. See API Key Management for details.

1. Install the SDK

npm install @fuul/sdk

# or using yarn
yarn add @fuul/sdk

2. Initialize

Before using any SDK method, initialize it with your API key at the root of your app:

import { Fuul } from '@fuul/sdk';

Fuul.init({ apiKey: 'your-api-key' });

When using Next.js App Router, initialize the SDK in a client-rendered component ('use client').

Which API key should I use?

The API key you pass to Fuul.init() depends on what your app needs to do:

Use case	Key type
Display leaderboards, rewards, or user data	read-only
Track pageviews and wallet connections (frontend)	send:tracking_event
Send custom trigger events (backend only)	send:trigger_event
Manage audiences programmatically (backend only)	service_role

Most frontend integrations use the send:tracking_event key, which covers both reading data and sending tracking events.

What's next?

After initializing the SDK, the typical integration steps are:

Step	Page
Track referral visits and wallet connections	Tracking Referrals
Let users create affiliate links or codes	Affiliate Links & Codes
Display leaderboard rankings	Leaderboard Data
Show individual user rewards	Individual Rewards
Build a claiming page for onchain rewards	Claiming Onchain Rewards

For a high-level overview of which features require SDK integration, see Build Your Incentives Hub.