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 custom parameters — see complete documentation below.
Track Function
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
Example to track two different generic events:
Event of type "click":
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
andcustom_nr_1_value
→ 1st NUMERICAL label and its valuecustom_nr_2_label
andcustom_nr_2_value
→ 2nd NUMERICAL label and its valuecustom_nr_3_label
andcustom_nr_3_value
→ 3rd NUMERICAL label and its valuecustom_nr_4_label
andcustom_nr_4_value
→ 4th NUMERICAL label and its valuecustom_nr_5_label
andcustom_nr_5_value
→ 5th NUMERICAL label and its value
TEXTUAL custom
parameters
:custom_str_1_label
andcustom_str_1_value
→ 1st TEXTUAL label and its valuecustom_str_2_label
andcustom_str_2_value
→ 2nd TEXTUAL label and its valuecustom_str_3_label
andcustom_str_3_value
→ 3rd TEXTUAL label and its valuecustom_str_4_label
andcustom_str_4_value
→ 4th TEXTUAL label and its valuecustom_str_5_label
andcustom_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:
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.
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
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.
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:
Example with the suggested field fromAmountUSD
:
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.
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:
Example with the suggested field amountUSD
:
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.
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:
Example with the suggested field amountUSD
:
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.
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:
Example with the suggested field amountUSD
:
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.
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:
Example only with required telegram field:
Example with optional name field 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-mail
and (optionally) name
as attributes in the field parameters
.
string
Required
Authenticated e-mail
name
string
Optional
Name of account
Example only with required email field:
Example with optional name field included:
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).
twitter_username
string
Required *
*Optional when lens_handle
or farcaster_id
is set
lens_handle
string
Required *
*Optional when twitter_username
or farcaster_id
is set
farcaster_id
number
Required *
*Optional when twitter_username
or farcaster_id
is set
Example only with required twitter_username
field:
Example only with required lens_handle
field:
Example only with required farcaster_id
field:
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
.
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:
Example with the suggested fields:
See the last section of this page for troubleshooting.
Example using Typescript
Step 1: Declaring safary
in the window object.
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:
To track a "swap event following our standards define above, including the optional field (
fromAmountUSD
) and an additional information (chainId
):
Troubleshooting
Required arguments:
Note that
eventType
+eventName
are required arguments forsafary.track
.Therefore, for example, the following would not work:
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:
Last updated