This is the shared analytics package for Trezor Suite, containing all event types used across the app. It is designed to work in both web and native (mobile) environments.

Depending on your platform, you can choose one of the following packages. Each with its own set of events:

Package	Platform	Events Defined In
`@suite/analytics`	`desktop`	`suite/analytics/src/events`
`@suite-native/analytics`	`mobile`	`suite-native/analytics/src/events`
`@suite-common/analytics`	`mobile & desktop`	`suite-common/analytics/src/events`

Data in these packages is the only source of truth. More details can be found in the company Notion.

Tracking

Data from production builds (codesign branch) should be sent to:

Desktop build: https://data.trezor.io/suite/log/desktop/stable.log
Web build: https://data.trezor.io/suite/log/web/stable.log
Mobile build: https://data.trezor.io/suite/log/mobile/stable.log

Data from development builds should be sent to:

Desktop build: https://data.trezor.io/suite/log/desktop/develop.log
Web build: https://data.trezor.io/suite/log/web/develop.log
Mobile build: https://data.trezor.io/suite/log/mobile/develop.log

Add/Modify event

In case a new event has to be added or an old one has to be modified, please follow the following subsections.

What to track

Navigation between pages is not required to be tracked as it is tracked automatically by router/location-change event. However, a case when it is good to track it is when a user can get to the same location using different methods (e.g. two different buttons on the same page). All other user actions without sensitive info can be tracked. If you are in doubt, please contact our analyst.

Type declaration

All events and their data and attributes should be declared in separated files in src/events and exported in src/events/index.ts. Selected package is depending on a platform as it's shown in the table above.

Example of an event (and its attributes) definition:

import type { AttributeDef, EventDef } from '@suite-common/analytics';

import { EventType } from '../constants';

type Attributes = {
    action: AttributeDef<'cta' | 'close'>;
    bannerType?: AttributeDef<string | null>;
};

export const promoDashboardBannerEvent: EventDef<Attributes, EventType.PromoDashboardBanner> = {
    name: EventType.PromoDashboardBanner,
    descriptionTrigger: 'A user clicks the dashboard promo banner',
    changelog: [{ version: '25.8.0', notes: 'added' }],

    attributes: {
        action: {
            changelog: [{ version: '25.8.0', notes: 'added' }],
        },
        bannerType: {
            limitations: 'only selected strings allowed (e.g. `tex` and `ts7`)',
            changelog: [{ version: '25.8.0', notes: 'added' }],
        },
    },
};

Event types should be declared in the EventType enum in src/events/suite/constants.ts.

Reporting in code

To report an event, import analytics from the package based on your environment and initialize analytics (as soon as app starts).

// Desktop analytics
import { useAnalytics } from '@suite/analytics';
// Mobile analytics
import { useAnalytics } from '@suite-native/analytics';
// Shared (desktop & mobile) analytics
import { useAnalytics } from '@suite-common/analytics-redux';

const analytics = useAnalytics();

analytics.init(enabled, {
    instanceId,
    sessionId,
    environment,
    commitId,
    isDev,
    callbacks: {
        onEnable: () => ...,
        onDisable: () => ...,
    },
});

After that, you can use report method anywhere in your project scope.

analytics.report({
    type: 'event',
    payload: {
        attribute: attributeValue,
    },
});

In thunks you can use extra argument to get access to analytics:

export const sessionRequestThunk = createThunk<
    void,
    {
        event: WalletKitTypes.SessionRequest;
    }
>(`${WALLETCONNECT_MODULE}/sessionRequestThunk`, async ({ event }, { dispatch, extra }) => {
    extra.services.analytics.report({
        type: EventType.WalletConnectSessionRequest,
        payload: {
            origin: event.verifyContext.verified.origin,
            chainId: event.params.chainId,
            method: event.params.request.method,
        },
    });
});

Versioning

From Suite version 22.10.1, analytics uses Suite versioning. That means that the analytics version will change even if there are no changes in the analytics changelog. However, there can be changes in Suite functionality, which can also change the behavior of analytics.

Changelog

Any change in event or attribute should be documented in the changelog section of the event or attribute definition. The changelog entry should contain the version when the change was made and notes describing the change.

How to check that events are tracked?

Option: Open DevTools, navigate to Network tab, filter traffic by .log and check the Query String Parameters section
Option: Get access to Keboola via an access form (link in company Notion)
Option: Create a modified build of the app with an analytics server URL pointing to your server

Suite Native:

Option: Set the environment variable EXPO_PUBLIC_IS_ANALYTICS_LOGGER_ENABLED=true and run the app. The logs will be printed to the console.