> For the complete documentation index, see [llms.txt](https://safary-1.gitbook.io/safary-doc-2.0/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://safary-1.gitbook.io/safary-doc-2.0/connect-data/setup-events.md).

# Setup Events

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.

<figure><img src="/files/8q78WK1vkyJYqcN2ya0Y" alt=""><figcaption></figcaption></figure>

{% embed url="<https://www.loom.com/share/2416750c087643a386e81864af5a4daf?sid=4632ec56-9337-406f-a7b1-b7d5933d56ce>" %}

***

## Table of contents

1. [Setup event in Safary App ](#setup-event-in-safary-app)
2. [Track function](#track-function)
   1. [Custom parameters](#custom-parameters)
3. [Swap Event](#swap-event)
4. [Deposit Event](#deposit-event)
5. [Withdrawal Event](#withdrawal-event)
6. [NFT Purchase Event](#nft-purchase-event)
7. [Swap Request Event](#swap-request-event)
8. [Example using Typescript](#example-using-typescript)
9. [Troubleshooting](#troubleshooting)

***

## **Setup event in Safary App**&#x20;

***

## Track Function

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

<table><thead><tr><th width="139">FIELD</th><th width="83">TYPE</th><th width="105">USE</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td>eventType</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>Type/Category of the event. For example: “click”, “stake”, “swap”.</td></tr><tr><td>eventName</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>Specific name of the event of the type defined. For example: “submit button”, “swap offer 1”, “buy in main page”.</td></tr><tr><td>parameters</td><td>object</td><td>Optional</td><td>A dictionary of properties for the specific event being tracked. See the <a href="#custom-parameters">Custom Parameters subsection</a> for details on how to fill this field.</td></tr></tbody></table>

Example to track two different **generic** events:

* Event of type "click":

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

### Custom Parameters <a href="#custom-parameters" id="custom-parameters"></a>

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`:
  * `customNr1Label` and `customNr1Value`  → 1st NUMERICAL label and its value
  * `customNr2Label` and `customNr2Value`  → 2nd NUMERICAL label and its value
  * `customNr3Label` and `customNr3Value`  → 3rd NUMERICAL label and its value
  * `customNr4Label` and `customNr4Value`  → 4th NUMERICAL label and its value
  * `customNr5Label` and `customNr5Value`  → 5th NUMERICAL label and its value
* TEXTUAL custom `parameters`:
  * `customStr1Label` and `customStr1Value`  → 1st TEXTUAL label and its value
  * `customStr2Label` and `customStr2Value`  → 2nd TEXTUAL label and its value
  * `customStr3Label` and `customStr3Value`  → 3rd TEXTUAL label and its value
  * `customStr4Label` and `customStr4Value`  → 4th TEXTUAL label and its value
  * `customStr5Label` and `customStr5Value`  → 5th TEXTUAL label and its value

{% hint style="danger" %}
Please note these use **camel case** format, i.e. their names are all lowercase with first letter uppercase.\
Therefore, parameters will **NOT** be parsed if using a different format.
{% endhint %}

{% hint style="success" %}
Inside Safary's dashboards, you will be able to query these custom parameters based on the LABEL you define on  `customNr#Label` and `customStr#Label` .
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

Example of use:

```javascript
safary.track( { eventType: "add-to-favorites", 
                eventName: "main offer",
                parameters: { 
                    customNr1Label: "price",
                    customNr1Value: 0.001, 
                    customStr1Label: "fromCurrency",
                    customStr1Value: "ETH"
                    customStr2Label: "toCurrency",
                    customStr2Value: "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 <mark style="color:red;">**required**</mark> attributes in the field `parameters`, which are listed below.

{% hint style="info" %}
&#x20;You can also add any other desired fields in `parameters` as long as you follow the guidelines in the [Custom Parameters subsection](#custom-parameters). See examples below for this event.
{% endhint %}

{% hint style="danger" %}
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.<br>
{% endhint %}

<table><thead><tr><th width="176">parameters</th><th width="91">TYPE</th><th width="110">USE</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td>walletAddress</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The wallet address being used for the swap.</td></tr><tr><td>fromAmount</td><td>number</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The amount from which the swap is occurring.</td></tr><tr><td>fromCurrency</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The currency from which the swap is occurring.</td></tr><tr><td>fromAmountUsd</td><td>number</td><td>Optional</td><td>The amount from which the swap is occurring in <strong>USD</strong>. Fill if the USD amount is available during the function call.</td></tr><tr><td>contractAddress</td><td>string</td><td>Optional</td><td>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.</td></tr><tr><td>toAmount</td><td>number</td><td>Optional</td><td>The amount to which the swap is occurring.</td></tr><tr><td>toCurrency</td><td>string</td><td>Optional</td><td>The currency to which the swap is occurring.</td></tr><tr><td>toAmountUsd</td><td>number</td><td>Optional</td><td>The amount to which the swap is occurring in <strong>USD</strong>. Fill if the USD amount is available during the function call.</td></tr></tbody></table>

Example only with required fields:

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

Example with the suggested field `fromAmountUsd`:

```typescript
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](#custom-parameters). 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:

```typescript
safary.track({
            eventType: "swap",
            eventName: "swaps-main",
            parameters: { 
                walletAddress: "0x9999999999999",
                fromAmount: 0.001,
                fromCurrency: "ETH",
                fromAmountUsd: 1.8,
                toAmountUsd: 3,
                contractAddress: "0x000000000000",
                customStr1Label: "promotion",
                customStr1Value: "launch2025",
                customNr1Label: "wallet_count",
                customNr1Value: 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 <mark style="color:red;">**required**</mark> attributes in the field `parameters`, which are listed below.

{% hint style="info" %}
&#x20;You can also add any other desired fields in `parameters` as long as you follow the guidelines in the [Custom Parameters subsection](#custom-parameters). See examples below for this event.
{% endhint %}

{% hint style="danger" %}
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.
{% endhint %}

<table><thead><tr><th width="174">parameters</th><th width="93">TYPE</th><th width="105">USE</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td>walletAddress</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The wallet address being used for the deposit.</td></tr><tr><td>amount</td><td>number</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The amount being deposited.</td></tr><tr><td>currency</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The currency of the amount being deposited.</td></tr><tr><td>amountUsd</td><td>number</td><td>Optional</td><td>The amount being deposited in USD. Fill if the USD amount is available during the function call.</td></tr><tr><td>contractAddress</td><td>string</td><td>Optional</td><td>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.</td></tr></tbody></table>

Example only with required fields:

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

Example with the suggested field `amountUsd`:

```typescript
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](#custom-parameters). 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:

```typescript
safary.track({
            eventType: "deposit",
            eventName: "deposit-promo-01",
            parameters: { 
                walletAddress: "0x9999999999999",
                amount: 0.001,
                currency: "ETH",
                amountUsd: 1.8,
                contractAddress: "0x1111111111111",
                customStr1Label: "transactionHash",
                customStr1Value: "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 <mark style="color:red;">**required**</mark> attributes in the field `parameters`, which are listed below.

{% hint style="info" %}
&#x20;You can also add any other desired fields in `parameters` as long as you follow the guidelines in the [Custom Parameters subsection](#custom-parameters). See examples below for this event.
{% endhint %}

{% hint style="danger" %}
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.
{% endhint %}

<table><thead><tr><th width="171">parameters</th><th width="93">TYPE</th><th width="100">USE</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td>walletAddress</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The wallet address used for the withdrawal.</td></tr><tr><td>amount</td><td>number</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The amount being withdrawn.</td></tr><tr><td>currency</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The currency of the amount being withdrawn.</td></tr><tr><td>amountUsd</td><td>number</td><td>Optional</td><td>The amount being withdrawn in USD. Fill if the USD amount is available during the function call.</td></tr><tr><td>contractAddress</td><td>string</td><td>Optional</td><td>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.</td></tr></tbody></table>

Example only with required fields:

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

Example with the suggested field `amountUSD`:

```typescript
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](#custom-parameters). 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:

```typescript
safary.track({
            eventType: "withdrawal",
            eventName: "withdrawal-mtd-12",
            parameters: { 
                walletAddress: "0x9999999999999",
                amount: 0.001,
                currency: "ETH",
                amountUsd: 1.8,
                contractAddress: "0x1111111111111",
                customStr1Label: "transactionHash",
                customStr1Value: "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 <mark style="color:red;">**required**</mark> attributes in the field `parameters`, which are listed below.

{% hint style="info" %}
&#x20;You can also add any other desired fields in `parameters` as long as you follow the guidelines in the [Custom Parameters subsection](#custom-parameters). See examples below for this event.
{% endhint %}

{% hint style="danger" %}
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.
{% endhint %}

<table><thead><tr><th width="175">parameters</th><th width="91">TYPE</th><th width="104">USE</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td>walletAddress</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The wallet address used for the purchase.</td></tr><tr><td>amount</td><td>number</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The amount of the NFT purchase.</td></tr><tr><td>currency</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The currency of the amount of the NFT purchase.</td></tr><tr><td>amountUsd</td><td>number</td><td>Optional</td><td>The amount of the NFT purchase in USD. Fill if the USD amount is available during the function call.</td></tr><tr><td>contractAddress</td><td>string</td><td>Optional</td><td>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.</td></tr><tr><td>tokenId</td><td>number</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The token id of the NFT referenced in the contract address.</td></tr></tbody></table>

Example only with required fields:

```typescript
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`:

```typescript
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](#custom-parameters). 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:

```typescript
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,
                customStr1Label: "transactionHash",
                customStr1Value: "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 <mark style="color:red;">**required**</mark> attributes, which are listed below, and any other information you deem important in the field `parameters`.&#x20;

{% hint style="info" %}
&#x20;You can also add any other desired fields in `parameters` as long as you follow the guidelines in the [Custom Parameters subsection](#custom-parameters). See examples below for this event.
{% endhint %}

{% hint style="warning" %}
Note that this function creates a "Click" event called "Swap Request" and also **two** **wallet connections** for the active user session.
{% endhint %}

{% hint style="danger" %}
Since this is a special event that triggers others, it does **not** require an `eventType` .
{% endhint %}

{% hint style="danger" %}
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.
{% endhint %}

<table><thead><tr><th width="196">fields</th><th width="91">TYPE</th><th width="110">USE</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td>eventName</td><td>string</td><td>Optional</td><td>Name to specify a certain swap. If not filled, will be the default value "Swap Request".</td></tr><tr><td>fromAmount</td><td>number</td><td>Optional</td><td>The amount being from which the swap is occurring.</td></tr><tr><td>fromCurrency</td><td>string</td><td>Optional</td><td>The currency from which the swap is occurring.</td></tr><tr><td>fromAmountUsd</td><td>number</td><td>Optional</td><td>The currency from which the swap is occurring in USD. Fill if the USD amount is available during the function call.</td></tr><tr><td>fromWalletAddress</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The wallet address from which the swap is occurring.</td></tr><tr><td>fromChain</td><td>number or string</td><td>Optional</td><td>The chain (id or name) from which the swap is occurring.</td></tr><tr><td>toAmount</td><td>number</td><td>Optional</td><td>The amount being to which the swap is occurring.</td></tr><tr><td>toCurrency</td><td>string</td><td>Optional</td><td>The currency to which the swap is occurring.</td></tr><tr><td>toAmountUsd</td><td>number</td><td>Optional</td><td>The currency to which the swap is occurring in USD. Fill if the USD amount is available during the function call.</td></tr><tr><td>toWalletAddress</td><td>string</td><td><mark style="color:red;"><strong>Required</strong></mark></td><td>The wallet address to which the swap is occurring.</td></tr><tr><td>toChain</td><td>number or string</td><td>Optional</td><td>The chain (id or name) to which the swap is occurring.</td></tr><tr><td>parameters</td><td><strong>object</strong></td><td>Optional</td><td>Any other information you believe is useful to track. <strong>Needs to be an object.</strong></td></tr></tbody></table>

Example only with required fields:

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

Example with the suggested fields:

```typescript
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](#custom-parameters) — see the following example with additional custom information:

```typescript
safary.trackSwapRequest({
    fromWalletAddress: "0x9999999999999",
    toWalletAddress: "0x5555555555555",
    parameters: { 
        customStr1Label: "swapPage",
        customStr1Value: "secondary",
        customStr2Label: "button",
        customStr2Value: "submit"
    }
})
```

See the last section of this page for troubleshooting.

***

## Example using Typescript

**Step 1:** Declaring `safary` in the window object.

```typescript
declare global {
  interface Window {
    safary?: {
      track: (args: {
        eventType: string
        eventName: string
        parameters?: { [key: string]: string | number }
      }) => 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:

```typescript
window.safary?.track({
  eventType: 'click',
  eventName: 'signup',
  parameters: {
    customStr1Label: 'button_id',
    customStr1Value: (contextualData.get('button-id') as string) || '',
    customStr2Label: 'funnel_step',
    customStr2Value: (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`):

```typescript
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),
    customStr1Label: 'chainId',
    customStr1Value: (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:

```tsx
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:

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