top-analyze-sdk/README.md

SDK for TOP analytics

# Top Analyze SDK

Automatic analytics for TG Mini Apps with minimal integration.

## Quick Start

```bash
npm install top-analyze-sdk
```

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

// Initialize with required apiToken
const analytics = new TopAnalyzeSDK({
  appName: 'MyTonApp',
  apiToken: 'your-api-token',
});
analytics.start();
```

## 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)

### 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

```typescript
const analytics = new TopAnalyzeSDK({
  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, you need to attach your TON Connect instance using the `attachTonConnect` method.

### With @tonconnect/ui-react

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

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

// Hook for TON Connect integration
export const useTonConnectAnalytics = () => {
  const [tonConnectUI] = useTonConnectUI();

  useEffect(() => {
    if (!analytics || !tonConnectUI) return;

    // Attach TON Connect to analytics
    analytics.attachTonConnect(tonConnectUI);
  }, [tonConnectUI]);
};
```

### With custom adapter

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

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

// Create adapter for compatibility
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,
};

// Attach TON Connect to analytics
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 TopAnalyzeSDK({
  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
}
```

## Contact

Telegram: [@Ektomorphine](https://t.me/Ektomorphine)