Draswap Labs Analytics

The @draswap/analytics package is a npm package of React components and functions used to provide Analytics capability to Draswap Labs products.

This package is intended to be used with the @draswap/analytics-events package, which provides the constant definitions used inside this package.

Installation

Install via npm or yarn.

yarn add @draswap/analytics

npm i --save @draswap/analytics

Make sure the environment variable REACT_APP_STAGING is set to false in production.

Development

When making changes to this package, first ensure your changes are designed as needed by installing your changes from a tarball. To generate the tarball (with version 0.0.1 to indicate a test version) use the following command:

yarn tarball

To install in the relevant repo, copy the tarball to the root of your project's package.json and run the following commands in your project's root:

# yarn
yarn cache clean
yarn add file:draswap-analytics-dev.tgz

# npm
npm install draswap-analytics-dev.tgz

Alternatively, you can install with a direct file reference from your local analytics repository.

Once you have verified your changes, submit a PR, merge your code, and install the package directly from npm to pick up the official changes.

Release

Releasing is performed manually using the release Github workflow.

This repository uses semantic-release for the release process, which in turn uses the Angular commit message suggestions to identify the type of release.

Documentation

Initializing Analytics

The client should be initialized before it is used. To initialize the client, pass in the API key of the application, as well as the name of the application. If the application name is not listed under OriginApplication, it should be added under the enum. An additional configuration object can be passed.

import { initializeAnalytics, OriginApplication } from '@draswap/analytics'

initializeAnalytics(MY_API_KEY, OriginApplication.INTERFACE, {
    proxyUrl: MY_PROXY_URL
})

Note that an Error is thrown if the client is initialized more than once or if an invalid configuration object is provided.

Configuration Options

| Option | Type | Description | | :-------------- | :------ | :------------------------------------------------------------------------------------------- | | proxyUrl | string | The Amplitude URL to send events to. | | defaultEventName | string | When an event name is not provided, use the provided default. Defaults to Page Viewed. | | commitHash | string | The git commit hash to send with Trace events only. Does not send by default on raw events. | | isProductionEnv | boolean | When not set to true, user properties are not set on the Amplitude client. | | debug | boolean | When enabled, logs events to the console. Cannot be enabled while isProductionEnv is true. |

Logging Events Directly

Before logging an event, make sure to add it under the EventName enum in the @draswap/analytics-events package. To log an analytics event:

import { sendAnalyticsEvent } from '@draswap/analytics'
import { EventName, ElementName } from '@draswap/analytics-events'

sendAnalyticsEvent(EventName.PAGE_CLICKED, {
    elementName: ElementName.TOP_MENU
})

Using the Trace Component

There is also a built in React component that logs an event when it is first mounted. You may use it as a wrapper:

import { Trace } from '@draswap/analytics'
import { EventName, ModalName } from '@draswap/analytics-events'


<Trace name={EventName.TOKEN_SELECTOR_OPENED} modal={ModalName.TOKEN_SELECTOR}>
    <SomeComponent/>
</Trace>

Depending on the context that <Trace/> is used in, you may have to define new values in @draswap/analytics-events for the enums that are passed in as arguments such: BrowserEvent, EventName, ModalName, ElementName.

There is a React component that wraps event callbacks with logging logic:

import { TraceEvent } from '@draswap/analytics'
import { EventName, ElementName } from '@draswap/analytics-events'

<TraceEvent events={[Event.onClick]} name={EventName.SWAP_MAX_TOKEN_AMOUNT_SELECTED} element={ElementName.MAX_TOKEN_AMOUNT_BUTTON}>
    <SomeButton onClick={onClickHandler}/>
</TraceEvent>

Finally, you can set properties about the user of the application:

import { user } from 'analytics'
import { CustomUserProperties } from '@draswap/analytics-events'

user.set(CUSTOM_USER_PROPERTIES.DARK_MODE, isDarkMode)

Example Apps

This package is used into a few of Draswap Labs repos:

• Interface
• Docs

Legal notice

Draswap Labs encourages integrators to evaluate their own regulatory obligations when integrating this package into their products, including, but not limited to, those related to economic or trade sanctions compliance.