🎯Setup Events

Track any events on your website, like clicks, swaps, deposits and more.

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 custom parameters — see complete documentation below.

Table of contents

  1. Setup event in Safary App

  2. Track function

    1. Custom parameters

  3. Swap Event

  4. Deposit Event

  5. Withdrawal Event

  6. NFT Purchase Event

  7. Social Login Event

  8. Swap Request Event

  9. Example using Typescript

  10. Troubleshooting

Setup event in Safary App

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. See the Custom Parameters subsection for details on how to fill this field.

Example to track two different generic events:

  • Event of type "click":

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

Custom Parameters

To help the visualization of custom data for standard events in Safary's dashboards, our functions include a parameters field, which can include up to 5 numerical values and 5 textual values, each with a custom name.

In the parameters field of our safary.track function you can set the following pairs of values:

  • NUMERICAL custom parameters:

    • custom_nr_1_label and custom_nr_1_value → 1st NUMERICAL label and its value

    • custom_nr_2_label and custom_nr_2_value → 2nd NUMERICAL label and its value

    • custom_nr_3_label and custom_nr_3_value → 3rd NUMERICAL label and its value

    • custom_nr_4_label and custom_nr_4_value → 4th NUMERICAL label and its value

    • custom_nr_5_label and custom_nr_5_value → 5th NUMERICAL label and its value

  • TEXTUAL custom parameters:

    • custom_str_1_label and custom_str_1_value → 1st TEXTUAL label and its value

    • custom_str_2_label and custom_str_2_value → 2nd TEXTUAL label and its value

    • custom_str_3_label and custom_str_3_value → 3rd TEXTUAL label and its value

    • custom_str_4_label and custom_str_4_value → 4th TEXTUAL label and its value

    • custom_str_5_label and custom_str_5_value → 5th TEXTUAL label and its value

Please note these use snake case format, i.e. their names are all lowercase and separated by underscore. Therefore, parameters will NOT be parsed if using a different format.

Inside Safary's dashboards, you will be able to query these custom parameters based on the LABEL you define on custom_nr_*_label and custom_str_*_label .

Unless specified by the other events in this page, any other field sent within parameters will NOT be parsed and therefore you will NOT be able to query it within Safary's dashboards.

Example of use:

safary.track( { eventType: "add-to-favorites", 
                eventName: "main offer",
                parameters: { 
                    custom_nr_1_label: "price",
                    custom_nr_1_value: 0.001, 
                    custom_str_1_label: "fromCurrency",
                    custom_str_1_value: "ETH"
                    custom_str_2_label: "toCurrency",
                    custom_str_2_value: "PEPE"
                } 
             } )

See more examples in the events below and go to 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.

You can also add any other desired fields in parameters as long as you follow the guidelines in the Custom Parameters subsection. See examples below for this event.

When sending values for fromAmount or toAmount , make sure to send the correct value! Sometimes protocols give amount and decimals , and the correct value would be amount / (10 ** decimals) Therefore, make sure to check if your amount is already properly formatted, to avoid sending the raw amount, and transform before sending if needed.

parameters
TYPE
USE
DESCRIPTION

walletAddress

string

Required

The wallet address being used for the swap.

fromAmount

number

Required

The amount from which the swap is occurring.

fromCurrency

string

Required

The currency from which the swap is occurring.

fromAmountUSD

number

Optional

The amount from which the swap is occurring in USD. Fill if the USD amount is available during the function call.

contractAddress

string

Optional

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.

toAmount

number

Optional

The amount to which the swap is occurring.

toCurrency

string

Optional

The currency to which the swap is occurring.

toAmountUSD

number

Optional

The amount to which the swap is occurring in USD. Fill if the USD amount is available during the function call.

Example only with required fields:

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

Example with the suggested field fromAmountUSD:

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

Please note that the parameters field can also include any other information you believe is useful to track, as long as you follow the guidelines in the Custom Parameters subsection. For example, in the case of swaps it might be interesting to add properties like the promotion and wallet_count - 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,
                toAmountUSD: 3,
                contractAddress: "0x000000000000",
                custom_str_1_label: "promotion",
                custom_str_1_value: "launch2025",
                custom_nr_1_label: "wallet_count",
                custom_nr_1_value: 3
            }
          })

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.

You can also add any other desired fields in parameters as long as you follow the guidelines in the Custom Parameters subsection. See examples below for this event.

When sending values for amount , make sure to send the correct value! Sometimes protocols give amount and decimals , and the correct value would be amount / (10 ** decimals) Therefore, make sure to check if your amount is already properly formatted, to avoid sending the raw amount, and transform before sending if needed.

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

Optional

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

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

Please note that the parameters field can also include any other information you believe is useful to track, as long as you follow the guidelines in the Custom Parameters subsection. 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",
                custom_str_1_label: "transactionHash",
                custom_str_1_value: "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.

You can also add any other desired fields in parameters as long as you follow the guidelines in the Custom Parameters subsection. See examples below for this event.

When sending values for amount , make sure to send the correct value! Sometimes protocols give amount and decimals , and the correct value would be amount / (10 ** decimals) Therefore, make sure to check if your amount is already properly formatted, to avoid sending the raw amount, and transform before sending if needed.

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

Optional

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

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

Please note that the parameters field can also include any other information you believe is useful to track, as long as you follow the guidelines in the Custom Parameters subsection. 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",
                custom_str_1_label: "transactionHash",
                custom_str_1_value: "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.

You can also add any other desired fields in parameters as long as you follow the guidelines in the Custom Parameters subsection. See examples below for this event.

When sending values for amount , make sure to send the correct value! Sometimes protocols give amount and decimals , and the correct value would be amount / (10 ** decimals) Therefore, make sure to check if your amount is already properly formatted, to avoid sending the raw amount, and transform before sending if needed.

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

Optional

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",
                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,
                tokenId: 1,
            }
          })

Please note that the parameters field can also include any other information you believe is useful to track, as long as you follow the guidelines in the Custom Parameters subsection. 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,
                custom_str_1_label: "transactionHash",
                custom_str_1_value: "0x123123123123123"
            }
          })

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.

You can also add any other desired fields in parameters as long as you follow the guidelines in the Custom Parameters subsection. See examples below for this event.

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 .

When sending values for fromAmount or toAmount , make sure to send the correct value! Sometimes protocols give amount and decimals , and the correct value would be amount / (10 ** decimals) Therefore, make sure to check if your amount is already properly formatted, to avoid sending the raw amount, and transform before sending if needed.

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, as long as you follow the guidelines in the Custom Parameters subsection — see the following example with additional custom information:

safary.trackSwapRequest({
    fromWalletAddress: "0x9999999999999",
    toWalletAddress: "0x5555555555555",
    parameters: { 
        custom_str_1_label: "swapPage",
        custom_str_1_value: "secondary",
        custom_str_2_label: "button",
        custom_str_2_value: "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: {
    custom_str_1_label: 'button_id',
    custom_str_1_value: (contextualData.get('button-id') as string) || '',
    custom_str_2_label: 'funnel_step',
    custom_str_2_value: (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),
    custom_str_1_label: 'chainId',
    custom_str_1_value: (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.
PreviousVia Google Tag ManagerNextSocial Logins

Last updated