Top Analyze SDK

Automatic analytics for TG Mini Apps with minimal integration.

Quick Start

npm install top-analyze-sdk

Using official Telegram SDK (window.Telegram.WebApp)

import { TelegramWebAppSDK } from 'top-analyze-sdk';

const analytics = new TelegramWebAppSDK({
  appName: 'MyTonApp',
  apiToken: 'your-api-token',
});
analytics.start();

Using alternative libraries (@twa-dev/sdk, @telegram-apps/sdk, etc.)

If you're using an alternative Telegram Mini Apps library instead of the official window.Telegram.WebApp, use SDKBase directly:

import { SDKBase } from 'top-analyze-sdk';
import { retrieveLaunchParams } from '@twa-dev/sdk';
import WebApp from '@twa-dev/sdk';

const launchParams = retrieveLaunchParams();

const analytics = new SDKBase({
  appName: 'MyTonApp',
  apiToken: 'your-api-token',
  debug: true,
  getUserData: () => {
    const user = launchParams.initData?.user;
    if (!user) return null;
    return {
      telegramId: user.id,
      locale: user.languageCode ?? 'en',
      premium: user.isPremium ?? false,
      telegramUsername: user.username,
      telegramFirstname: user.firstName,
      telegramLastname: user.lastName,
      telegramPlatform: launchParams.platform,
      startapp: launchParams.initData?.startParam,
    };
  },
  trackTelegramEvents: (listener) => {
    WebApp.onEvent('mainButtonClicked', () => listener('mainButtonClicked', {}));
    WebApp.onEvent('fullscreenChanged', () => listener('fullscreenChanged', {}));
    // Add more events as needed...

    return () => {
      WebApp.offEvent('mainButtonClicked');
      WebApp.offEvent('fullscreenChanged');
    };
  },
});
analytics.start();

Backward Compatibility

For backward compatibility, the old naming is still supported:

import { TopAnalyzeSDK } from 'top-analyze-sdk'; // Alias for TelegramWebAppSDK

What's Collected Automatically

Sessions

• Start/end session
• Duration, idle timeouts
• Page URL, referrer, User-Agent

Clicks and Taps

• Coordinates (page/client)
• DOM snapshot of target (tag, id, classes, attributes)
• Safe CSS selector and XPath
• Truncated text (with PII masking)

Telegram Events

• Main button clicked
• Back button clicked
• Settings button clicked
• And other Mini Apps events...

TON Connect

• Wallet connection request
• Connect/disconnect
• Wallet info (name, address)

Transactions

• transaction_sent_for_signature
• transaction_signed
• transaction_signing_failed
• Amount, recipient, transaction ID

Configuration

const analytics = new TelegramWebAppSDK({
  appName: 'MyTonApp',
  apiToken: 'your-api-token', // Required
  debug: true, // Detailed logs
  onlyImportantClicks: false, // Track only important clicks (buttons, links, etc.)
});

TON Connect Integration

To track TON Connect events, attach your TON Connect instance using the attachTonConnect method.

With @tonconnect/ui-react

import { useEffect } from 'react';
import { useTonConnectUI } from '@tonconnect/ui-react';
import { TelegramWebAppSDK } from 'top-analyze-sdk';

const analytics = new TelegramWebAppSDK({
  appName: 'MyTonApp',
  apiToken: 'your-api-token',
});

export const useTonConnectAnalytics = () => {
  const [tonConnectUI] = useTonConnectUI();

  useEffect(() => {
    if (!analytics || !tonConnectUI) return;
    analytics.attachTonConnect(tonConnectUI);
  }, [tonConnectUI]);
};

With custom adapter

import { TelegramWebAppSDK } from 'top-analyze-sdk';

const analytics = new TelegramWebAppSDK({
  appName: 'MyTonApp',
  apiToken: 'your-api-token',
});

const tonConnectAdapter = {
  sendTransaction: async (transaction) => {
    return await tonConnectUI.sendTransaction(transaction);
  },
  connect: async () => {
    return tonConnectUI.connect();
  },
  disconnect: async () => {
    await tonConnectUI.disconnect();
  },
  onStatusChange: (callback) => {
    tonConnectUI.onStatusChange(callback);
  },
  wallet: tonConnectUI.wallet,
};

analytics.attachTonConnect(tonConnectAdapter);

Custom Events

// Game events
analytics.track('game_start', { level: 1, mode: 'normal' });
analytics.track('game_score', { score: 1500, level: 3 });
analytics.track('game_end', { score: 1500, duration: 120 });

// Business events
analytics.track('purchase_intent', { item: 'premium', price: '0.1' });
analytics.track('feature_used', { feature: 'dark_mode' });

Getting Information

// Session info
const sessionInfo = analytics.getSessionInfo();
console.log(sessionInfo.sessionId, sessionInfo.duration);

// Wallet info
const walletInfo = analytics.getTonWalletInfo();
console.log(walletInfo?.address, walletInfo?.name);

// SDK status
const status = analytics.getStatus();
console.log(status.isStarted, status.isTonConnectAttached);

Lifecycle Management

const analytics = new TelegramWebAppSDK({
  appName: 'MyTonApp',
  apiToken: 'your-api-token',
});

analytics.start(); // Start tracking
analytics.stop();  // Stop (with sending remaining events)

Event Structure

All events have a unified structure:

interface AnalyticsEvent {
  type: EventType;      // Event type
  timestamp: number;    // Unix timestamp
  sessionId: string;    // Session ID
  appName: string;      // App name
  data: EventData;      // Specific data
}

API Reference

Classes

| Class | Description | |-------|-------------| | TelegramWebAppSDK | For official Telegram SDK (window.Telegram.WebApp) | | SDKBase | Base class for custom integrations | | TopAnalyzeSDK | Alias for TelegramWebAppSDK (backward compatibility) |

Types

| Type | Description | |------|-------------| | TelegramWebAppSDKOptions | Options for TelegramWebAppSDK | | SDKBaseOptions | Options for SDKBase (includes getUserData and trackTelegramEvents) | | OnTelegramEventFn | Type for trackTelegramEvents function |

Contact

Telegram: @Ektomorphine