🎛️Tracking referrals in your app

This guide shows how to send event data through the Fuul Web SDK

For Fuul to attribute conversion events to your visitors, you'll need to report the pageview and connect_wallet events.

These events must be sent using theSEND: TRACKING_EVENT API key.

Pageview event

Projects must send this event every time a user visits a page on their website. This should be implemented on all pages of the site.

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

await Fuul.sendPageview();

The Fuul SDK will get the parameters from the URL once a user enters the site. There is no need to persist these parameters when navigating through the app.

Identify user

Projects must identify the user event every time users connect a wallet or logs in to their website (both when connecting a wallet for the first time and when changing wallets during the session).

By calling the identifyUser method, a connect wallet event is sent.

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

await Fuul.identifyUser({
  identifier: "0x12345", // the address of the user
  identifierType: "evm_address", // evm_address | solana_address | xrpl_address 
  signature: "0x123485090123",
  signaturePublicKey: '0x12345' // Only for XRPL type signatures
  message: "Accept affiliate on 18-Aug 2023 00:00:00",
});

For smart contract accounts, the accountChainId must be added as follows:

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

await Fuul.identifyUser({
  identifier: "0x12345",
  identifierType: "evm_address",
  signature: "0x123485090123",
  message: "Accept affiliate on 18-Aug 2023 00:00:00",
  accountChainId: 1
});

The following networks are supported for smart contract wallets:

• Mainnet (Ethereum): 1

• Arbitrum: 42161

• Optimism: 10

• Polygon: 137

• Base: 8453

• zkSync Era: 324

• BNB Chain: 56

• Fantom: 250

• Avalanche (C-Chain): 43114

• Mode: 34443

• Abstract: 2741

• Bob: 60808

• Berachain: 80094

• Gravity Chain: 16

• Bitlayer: 200901

Sending event through the API

If you are identifying the user from the backend, you will have to send the connect wallet event using the API, following this pattern:

import requests

url = "https://api.fuul.xyz/api/v1/events"

payload = {
    "metadata": {
        "tracking_id": "trackingId123"
    },
    "name": "connect_wallet",
    "user": {
        "identifier": "0x12345",
        "identifier_type": "evm_address"  # evm_address | solana_address | xrpl_address
    },
    "signature": "0x123485090123",
    "signature_message": "Accept affiliate on 18-Aug 2023 00:00:00",
    "account_chain_id": 1  # Only for smart contract wallets
}

headers = {
    "content-type": "application/json",
    "authorization": "Bearer my-fuul-key"
}

response = requests.post(url, json=payload, headers=headers)

In this case, you will need to get the fuul.tracking_id from the browser's local storage. Remember that it must be the same one that was sent on the pageview event.

Message & Signature

Fuul allows two different types of signatures.

To validate regular signatures we use Viem verifyMessage and in the case of typed data signatures, we use Viem verifyTypedData.

In the case of typed data signatures, the payload should be the following:

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

const typedData = {
    address, domain, types, primaryType, message
}

await Fuul.identifyUser({ 
    userIdentifier: '0x12345',
    identifierType: "evm_address",
    message: JSON.stringify(typedData),
    signature: '0x123485090123',
});

Requiring users to sign a message ensures event validity and disclosure to the user. This is mandatory as it prevents attribution fraud.