Top Analyze SDK

Automatic analytics for TG Mini Apps with minimal integration.

Quick Start

``bash
npm install top-analyze-sdk
`

$3

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

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

$3

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

`typescript
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();
`

$3

For backward compatibility, the old naming is still supported:

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

What's Collected Automatically

$3

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

$3

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

$3

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

$3

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

$3

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

Configuration

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

$3

`typescript
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]);
};
`

$3

`typescript
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

`typescript
// 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

`typescript
// 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

`typescript
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:

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

API Reference

$3

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

$3

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

Contact

Telegram: @Ektomorphine