@mollie/ui-analytics

Installation

# With Jitsu backend (web)
yarn add @mollie/ui-analytics @jitsu/js

# With Segment backend (React Native)
yarn add @mollie/ui-analytics @segment/analytics-react-native

The core manager works without any backend — @jitsu/js and @segment/analytics-react-native are optional peer dependencies.

Without React (Vanilla JS/TS)

1. Subscribe to events

import { analyticsManager } from '@mollie/ui-analytics';
import { createAnalyticsSubscriber } from '@mollie/ui-analytics/jitsu';

const [subscribeFn, analytics] = createAnalyticsSubscriber({
  writeKey: 'your-write-key:secret',
  host: 'https://your-jitsu-host.example.com',
  debug: true, // optional
  privacy: false, // optional — strips IPs and disables user IDs when true
});

const unsubscribe = analyticsManager.subscribe(subscribeFn);

2. Emit events

analyticsManager.emit('button_clicked', {
  journey_name: 'onboarding',
  current_screen: 'signup',
  interaction_type: 'click',
  element_type: 'button',
  element_details: 'submit-form',
});

3. Identify users and track pages

analytics.identify('user-123', { email: '[email protected]' });
analytics.page('home', { referrer: 'google' });
analytics.reset(); // clear identity on logout

4. Decorate events globally

Decorators enrich every event that passes through the manager:

const undecorate = analyticsManager.decorate((event) => ({
  ...event,
  platform: 'web',
  app_version: '2.1.0',
}));

// Later: undecorate() to remove

5. Cleanup

unsubscribe(); // remove one subscriber
analyticsManager.clear(); // remove all subscribers, decorators, and history

With React

1. Set up the provider

import { createAnalyticsSubscriber } from '@mollie/ui-analytics/jitsu';
import {
  AnalyticsSubscriber,
  useAnalyticsSubscriber,
} from '@mollie/ui-analytics/react';

function App() {
  const [subscribeFn] = useAnalyticsSubscriber(() =>
    createAnalyticsSubscriber({
      writeKey: process.env.JITSU_WRITE_KEY,
      host: process.env.JITSU_HOST,
    })
  );

  return (
    <AnalyticsSubscriber
      onEvent={subscribeFn}
      onDecorateEvent={(event) => ({
        ...event,
        platform: 'web',
      })}
    >
      <Routes />
    </AnalyticsSubscriber>
  );
}

AnalyticsSubscriber handles subscribing and unsubscribing internally — no useEffect needed.

2. Emit events from components

import { useAnalyticsEmitter } from '@mollie/ui-analytics/react';

function SignupButton() {
  const emit = useAnalyticsEmitter();

  return (
    <button
      onClick={() =>
        emit('signup_started', {
          journey_name: 'onboarding',
          current_screen: 'landing',
          interaction_type: 'click',
        })
      }
    >
      Sign up
    </button>
  );
}

3. Add contextual decorators

Nest AnalyticsDecorator components to automatically enrich events emitted by descendants:

import { AnalyticsDecorator } from '@mollie/ui-analytics/react';

function SettingsPage() {
  return (
    <AnalyticsDecorator
      onEvent={(event) => ({
        ...event,
        current_screen: 'settings',
        journey_name: 'account_management',
      })}
    >
      <ProfileSection />
      <BillingSection />
    </AnalyticsDecorator>
  );
}

Decorators compose — inner decorators run after outer ones.

Event structure

Emitted properties are automatically transformed into a structured event:

| Context | Fields | | ---------------------- | --------------------------------------------------------------------------------------- | | journeyContext | journey_name, current_screen, entry_source, journey_entry_id, previous_action | | interactionDetails | interaction_type, element_type, element_details, input_details, time_spend_ms | | failureContext | failure_reason, failure_type, recovery_action | | systemContext | client_timestamp, platform, feature_flags |

journey_entry_id (UUID) and client_timestamp are auto-generated. previous_action is tracked automatically per journey_name.

Available enums

import {
  ElementType, // BUTTON, INPUT, FORM, DROPDOWN
  EntrySource, // NAVBAR, DEEP_LINK, NOTIFICATION, EMAIL, EXTERNAL
  FailureType, // VALIDATION, SYSTEM, USER_ABANDONED, TIMEOUT
  InputType, // TEXT, SELECTION, UPLOAD, SUBMIT
  InteractionType, // CLICK, VIEW, ELEMENT_RENDERED, INPUT, SYSTEM, FORM_SUBMIT
  Platform, // WEB, MOBILE_WEB, IOS, ANDROID
} from '@mollie/ui-analytics';

React Native

Use the native import paths — the API is identical:

import { useAnalyticsEmitter } from '@mollie/ui-analytics/react/native';
import { createAnalyticsSubscriber } from '@mollie/ui-analytics/jitsu/native';

The native Jitsu subscriber uses @segment/analytics-react-native under the hood with a proxy pointing to your Jitsu host.