# 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.
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://safary-1.gitbook.io/safary-doc-2.0/connect-data/setup-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.