Setup events

Track Custom Events using Safary's Javascript SDK

Safary makes available after document.readyState === 'complete' a method under window.safary.track, which can be executed while defining an event type, event name and additional parameters — see complete documentation below.

To help the visualization of common events in Safary's dashboards, below we also indicate how to fill the parameters field for some events, such as swap, deposit and withdrawal.

---

Track Function

safary.track({
            eventType: string,
            eventName: string,
            parameters: object
          })

FIELD	TYPE	USE	DESCRIPTION
eventType	string	Required	Type/Category of the event. For example: “click”, “stake”, “swap”.
eventName	string	Required	Specific name of the event of the type defined. For example: “submit button”, “swap offer 1”, “buy in main page”.
parameters	object	Optional	A dictionary of properties for the specific event being tracked. For example, if the event was “purchase”, it might have properties like “price” and “product”.

Example to track two different generic events:

• Event of type "click":

safary.track( { eventType: "click", eventName: "form submit" } 

• Event of type "add-to-favorites"

safary.track( { eventType: "add-to-favorites", 
                eventName: "main offer",
                parameters: { price: "0.001", currency: "ETH" } 
             } )

See the last section of this page for troubleshooting.

---

Swap Event

To track a swap event, use the track function with "swap" as the eventType, choose any name as eventName, and make sure to add all the required attributes in the field parameters, which are listed below.

parameters	TYPE	USE	DESCRIPTION
walletAddress	string	Required	The wallet address being used for the swap.
fromAmount	number	Required	The amount being from which the swap is occurring.
fromCurrency	string	Required	The currency from which the swap is occurring.
fromAmountUSD	number	Optional	The currency from which the swap is occurring in USD. Fill if the USD amount is available during the function call.
contractAddress	string	Required	The contract address related to the swap. This will be used in the future to check if the swap was actually successful using on-chain data.

Example only with required fields:

safary.track({
            eventType: "swap",
            eventName: "swaps-main",
            parameters: { 
                walletAddress: "0x9999999999999",
                fromAmount: 0.001,
                fromCurrency: "ETH",
                contractAddress: "0x000000000000",
            }
          })

Example with the suggested field fromAmountUSD:

safary.track({
            eventType: "swap",
            eventName: "swaps-main",
            parameters: { 
                walletAddress: "0x9999999999999",
                fromAmount: 0.001,
                fromCurrency: "ETH",
                fromAmountUSD: 1.8,
                contractAddress: "0x000000000000",
            }
          })

Please note that the parameters field can also include any other information you believe is useful to track. For example, in the case of swaps it might be interesting to add properties like the toAmount, toAmountUSD and toCurrency - see the following example with these additional information:

safary.track({
            eventType: "swap",
            eventName: "swaps-main",
            parameters: { 
                walletAddress: "0x9999999999999",
                fromAmount: 0.001,
                fromCurrency: "ETH",
                fromAmountUSD: 1.8,
                contractAddress: "0x000000000000",
                toAmount: 0.000045,
                toCurrency: "BTC",
                toAmountUSD: 1.73,
            }
          })

See the last section of this page for troubleshooting.

---

Deposit Event

To track a deposit event, use the track function with "deposit" as the eventType, choose any name as eventName, and make sure to add all the required attributes in the field parameters, which are listed below.

parameters	TYPE	USE	DESCRIPTION
walletAddress	string	Required	The wallet address being used for the deposit.
amount	number	Required	The amount being deposited.
currency	string	Required	The currency of the amount being deposited.
amountUSD	number	Optional	The amount being deposited in USD. Fill if the USD amount is available during the function call.
contractAddress	string	Required	The contract address related to the deposit. This will be used in the future to check if it was actually successful using on-chain data.

Example only with required fields:

safary.track({
            eventType: "deposit",
            eventName: "deposit-promo-01",
            parameters: { 
                walletAddress: "0x9999999999999",
                amount: 0.001,
                currency: "ETH",
                contractAddress: "0x1111111111111",
            }
          })

Example with the suggested field amountUSD:

safary.track({
            eventType: "deposit",
            eventName: "deposit-promo-01",
            parameters: { 
                walletAddress: "0x9999999999999",
                amount: 0.001,
                currency: "ETH",
                amountUSD: 1.8,
                contractAddress: "0x1111111111111",
            }
          })

Please note that the parameters field can also include any other information you believe is useful to track. For example, in the case of deposits it might be interesting to add a property like the transactionHash - see the following example with this additional information:

safary.track({
            eventType: "deposit",
            eventName: "deposit-promo-01",
            parameters: { 
                walletAddress: "0x9999999999999",
                amount: 0.001,
                currency: "ETH",
                amountUSD: 1.8,
                contractAddress: "0x1111111111111",
                transactionHash: "0x123123123123123",
            }
          })

See the last section of this page for troubleshooting.

---

Withdrawal Event

To track a withdrawal event, use the track function with "withdrawal" as the eventType, choose any name as eventName, and make sure to add all the required attributes in the field parameters, which are listed below.

parameters	TYPE	USE	DESCRIPTION
walletAddress	string	Required	The wallet address used for the withdrawal.
amount	number	Required	The amount being withdrawn.
currency	string	Required	The currency of the amount being withdrawn.
amountUSD	number	Optional	The amount being withdrawn in USD. Fill if the USD amount is available during the function call.
contractAddress	string	Required	The contract address related to the withdrawal. This will be used in the future to check if it was actually successful using on-chain data.

Example only with required fields:

safary.track({
            eventType: "withdrawal",
            eventName: "withdrawal-mtd-12",
            parameters: { 
                walletAddress: "0x9999999999999",
                amount: 0.001,
                currency: "ETH",
                contractAddress: "0x1111111111111",
            }
          })

Example with the suggested field amountUSD:

safary.track({
            eventType: "withdrawal",
            eventName: "withdrawal-mtd-12",
            parameters: { 
                walletAddress: "0x9999999999999",
                amount: 0.001,
                currency: "ETH",
                amountUSD: 1.8,
                contractAddress: "0x1111111111111",
            }
          })

Please note that the parameters field can also include any other information you believe is useful to track. For example, in the case of withdrawals it might be interesting to add a property like the transactionHash - see the following example with this additional information:

safary.track({
            eventType: "withdrawal",
            eventName: "withdrawal-mtd-12",
            parameters: { 
                walletAddress: "0x9999999999999",
                amount: 0.001,
                currency: "ETH",
                amountUSD: 1.8,
                contractAddress: "0x1111111111111",
                transactionHash: "0x123123123123123",
            }
          })

See the last section of this page for troubleshooting.

---

NFT Purchase Event

To track a NFT purchase event, use the track function with "NFT purchase" as the eventType, choose any name as eventName, and make sure to add all the required attributes in the field parameters, which are listed below.

parameters	TYPE	USE	DESCRIPTION
walletAddress	string	Required	The wallet address used for the purchase.
amount	number	Required	The amount of the NFT purchase.
currency	string	Required	The currency of the amount of the NFT purchase.
amountUSD	number	Optional	The amount of the NFT purchase in USD. Fill if the USD amount is available during the function call.
contractAddress	string	Required	The contract address related to the NFT purchase. This will be used in the future to check if it was actually successful using on-chain data.
tokenId	number	Required	The token id of the NFT referenced in the contract address.

Example only with required fields:

safary.track({
            eventType: "NFT purchase",
            eventName: "nft-mario-crypto-99",
            parameters: { 
                walletAddress: "0x9999999999999",
                amount: 0.001,
                currency: "ETH",
                contractAddress: "0x1111111111111",
                tokenId: 1,
            }
          })

Example with the suggested field amountUSD:

safary.track({
            eventType: "NFT purchase",
            eventName: "nft-mario-crypto-99",
            parameters: { 
                walletAddress: "0x9999999999999",
                amount: 0.001,
                currency: "ETH",
                amountUSD: 1.8,
                contractAddress: "0x1111111111111",
                tokenId: 1,
            }
          })

Please note that the parameters field can also include any other information you believe is useful to track. For example, in the case of NFT purchases it might be interesting to add a property like the transactionHash - see the following example with this additional information:

safary.track({
            eventType: "NFT purchase",
            eventName: "nft-mario-crypto-99",
            parameters: { 
                walletAddress: "0x9999999999999",
                amount: 0.001,
                currency: "ETH",
                amountUSD: 1.8,
                contractAddress: "0x1111111111111",
                tokenId: 1,
                transactionHash: "0x123123123123123",
            }
          })

See the last section of this page for troubleshooting.

---

Form Event

The form event can be used to track user information. To track a form submission event, use the track function with "form" as the eventType, and any appropriate name as eventName, and make sure to add the required attributes in the field parameters. The parameters field can contain an email or a telegram username, optionally including the user's name.

parameters	TYPE	USE	DESCRIPTION
email	string	Required *	*optional when telegram is set
telegram	string	Required *	Telegram username *optional when email is set
name	string	Optional

Example only with required email field:

safary.track({
  eventType: "form",
  eventName: "newsletter-signup",
  parameters: { 
    email: "[e-mail]"
  }
})

Example only with required telegram field:

safary.track({
  eventType: "form",
  eventName: "telegram-signup",
  parameters: { 
    telegram: "user123"
  }
})

Example with optional name field included:

safary.track({
  eventType: "form",
  eventName: "newsletter-signup",
  parameters: { 
    email: "[e-mail]",
    name: "John Doe"
  }
})

safary.track({
  eventType: "form",
  eventName: "telegram-signup",
  parameters: { 
    telegram: "user123",
    name: "Jane Doe"
  }
})

Please note that the parameters field can also include any other information you believe is useful to track. For form submissions, additional properties relevant to your application's needs might be included.

See the last section of this page for troubleshooting.

---

Google Auth Event

The form event can also be used to track user information after authenticating with Google. Simply submit an event with "form" as the eventType, any appropriate name as eventName, and add the e-mailand (optionally) name as attributes in the field parameters.

parameters	TYPE	USE	DESCRIPTION
email	string	Required	Authenticated e-mail
name	string	Optional	Name of account

Example only with required email field:

safary.track({
  eventType: "form",
  eventName: "google-auth",
  parameters: { 
    email: "[e-mail]"
  }
})

Example with optional name field included:

safary.track({
  eventType: "form",
  eventName: "google-auth",
  parameters: { 
    email: "[e-mail]",
    name: "John Doe"
  }
})

Please note that the parameters field can also include any other information you believe is useful to track.

See the last section of this page for troubleshooting.

---

Social Login Event

The social_login event can be used to track information regarding logins made using socials. To track a social login event, use the track function with "social_login" as the eventType, and any appropriate name as eventName, and make sure to add the required attributes in the field parameters.

The parameters field should contain at least one of the three possible fields: twitter_username, lens_handle and farcaster_id described below. (note these field names are case sensitive).

parameters	TYPE	USE	DESCRIPTION
twitter_username	string	Required * *Optional when lens_handle or farcaster_id is set	Twitter/X username. For example, for https://x.com/safaryclub, send only "safaryclub".
lens_handle	string	Required * *Optional when twitter_username or farcaster_id is set	Lens handle without the namespace. For example, for https://hey.xyz/u/ricardocarvalho send only "ricardocarvalho"
farcaster_id	number	Required * *Optional when twitter_username or farcaster_id is set	Farcaster ID (aka FID). For example, for https://warpcast.com/jhv click on the three dots and then click on "About" to see the FID of 1385.

Example only with required twitter_username field:

safary.track({
  eventType: "social_login",
  eventName: "login-using-twitter",
  parameters: { 
    twitter_username: "elonmusk"
  }
})

Example only with required lens_handle field:

safary.track({
  eventType: "social_login",
  eventName: "login-using-lens",
  parameters: { 
    lens_handle: "ricardocarvalho"
  }
})

Example only with required farcaster_id field:

safary.track({
  eventType: "social_login",
  eventName: "login-using-farcaster",
  parameters: { 
    farcaster_id: "jhv"
  }
})

Please note that the parameters field can also include any other information you believe is useful to track. For form submissions, additional properties relevant to your application's needs might be included.

See the last section of this page for troubleshooting.

See the last section of this page for troubleshooting.

---

Swap Request Event

To track the request for a swap event that also carries wallet information related to the swap for the current session of a user, use the trackSwapRequest function with any name as eventName, and make sure to add all the required attributes, which are listed below, and any other information you deem important in the field parameters.

Note that this function creates a "Click" event called "Swap Request" and also two wallet connections for the active user session.

Since this is a special event that triggers others, it does not require an eventType .

fields	TYPE	USE	DESCRIPTION
eventName	string	Optional	Name to specify a certain swap. If not filled, will be the default value "Swap Request".
fromAmount	number	Optional	The amount being from which the swap is occurring.
fromCurrency	string	Optional	The currency from which the swap is occurring.
fromAmountUSD	number	Optional	The currency from which the swap is occurring in USD. Fill if the USD amount is available during the function call. Note that in the field name, USD is all uppercase.
fromWalletAddress	string	Required	The wallet address from which the swap is occurring.
fromChain	number or string	Optional	The chain (id or name) from which the swap is occurring.
toAmount	number	Optional	The amount being to which the swap is occurring.
toCurrency	string	Optional	The currency to which the swap is occurring.
toAmountUSD	number	Optional	The currency to which the swap is occurring in USD. Fill if the USD amount is available during the function call. Note that in the field name, USD is all uppercase.
toWalletAddress	string	Required	The wallet address to which the swap is occurring.
toChain	number or string	Optional	The chain (id or name) to which the swap is occurring.
parameters	object	Optional	Any other information you believe is useful to track. Needs to be an object.

Example only with required fields:

safary.trackSwapRequest({
    fromWalletAddress: "0x9999999999999",
    toWalletAddress: "0x5555555555555"
})

Example with the suggested fields:

safary.trackSwapRequest({
    fromAmount: 0.001,
    fromCurrency: "ETH",
    fromAmountUSD: 3,
    fromWalletAddress: "0x9999999999999",
    fromChain: 8453,
    toAmount: 0.0005,
    toCurrency: "ETH",
    toAmountUSD: 2,
    toWalletAddress: "0x5555555555555",
    toChain: 1,
})

Please note that the parameters field can include any other information you believe is useful to track — see the following example with additional information:

safary.trackSwapRequest({
    fromWalletAddress: "0x9999999999999",
    toWalletAddress: "0x5555555555555",
    parameters: { 
        swapPage: "secondary",
        button: "submit"
    }
})

See the last section of this page for troubleshooting.

---

Example using Typescript

Step 1: Declaring safary in the window object.

declare global {
  interface Window {
    safary?: {
      track: (args: {
        eventType: string
        eventName: string
        parameters?: { [key: string]: string | number | boolean }
      }) => void
    }
  }
}

Step 2: In your code, when some action you want to track is triggered, containing, for example, some contextualData, you can use safary.track as follows.

• To track any custom event, for example, a "click" event:

window.safary?.track({
  eventType: 'click',
  eventName: 'signup',
  parameters: {
    button: (contextualData.get('button-id') as string) || '',
    funnel_step: (contextualData.get('page-url') as string) || '',
  },
})

• To track a "swap event following our standards define above, including the optional field (fromAmountUSD) and an additional information (chainId):

window.safary?.track({
  eventType: 'swap',
  eventName: 'swap-main',
  parameters: {
    walletAddress: (contextualData.get('walletAddress') as string),
    fromAmount: (contextualData.get('amount') as number),
    fromCurrency: (contextualData.get('currency') as string),
    fromAmountUSD: (contextualData.get('amountUSD') as number),
    contractAddress: (contextualData.get('contractAddress') as string),
    chainId: (contextualData.get('chainId') as string) || '',
  },
})

---

Troubleshooting

Required arguments:

• Note that eventType + eventName are required arguments for safary.track .

• Therefore, for example, the following would not work:

safary.track( { eventName: "main offer" } )
// Gives:
// ERROR: safary.track(): eventType is undefined.

Required format:

• Note that the parameters used in the both tracking functions is required to be an object.

• Therefore, for example, passing a string as parameters would not work:

safary.track( { eventType: "buy", eventName: "main offer", parameters: "ETH" } )
// Gives:
// ERROR: safary.track(): parameters is not an object.