​
System Requirements

  • A package manager such as npm (version 6 or newer) or yarn
  • A Telegram Mini App project set up with React
React boilerplate to jumpstart using Telemetree

​
Installation

Install Telemetree React SDK using npm or yarn 
npm install @tonsolutions/telemetree-react
This will add the Telemetree React SDK to your project and you’re ready to proceed to the next steps of configuration and event tracking.

​
Initialization

To begin using the Telemetree React SDK in your application, you’ll need to initialize it with your project’s specific configuration. Initialization is a crucial step that allows the SDK to start capturing and sending analytics data.

​
Step-by-Step Initialization

  1. Add the script to your index.html file in the <head>:
<script src="https://telegram.org/js/telegram-web-app.js"></script>
or if you prefer using Telegram SDK, for example when building with Nextjs: 
npm install @twa-dev/sdk
  1. Import the SDK: Start by importing the Telemetree provider into your main application file, typically App.js.
  2. Wrap Your Application: Use the TwaAnalyticsProvider component to wrap your application’s root component. This enables analytics tracking throughout your app
  3. Configure the Provider: Replace 'YOUR_PROJECT_ID', 'YOUR_API_KEY', and 'YOUR_APPLICATION_NAME' with the actual values provided when you set up your Telemetree account. 
import { TwaAnalyticsProvider } from '@tonsolutions/telemetree-react';
// If you use Telegram SDK also add:
// import WebApp from '@twa-dev/sdk'

export function App() {
    return (
    <TwaAnalyticsProvider
        projectId='YOUR_PROJECT_ID'
        apiKey='YOUR_API_KEY'
        appName='YOUR_APPLICATION_NAME'
    >
        {/* Rest of your app components */}
    </TwaAnalyticsProvider>
    );
}
After wrapping your root component with TwaAnalyticsProvider, the SDK will automatically start capturing data based on your configuration.

​
User Identification and Profiles

​
Automated User Data Enrichment

Telemetree’s React SDK automatically enriches each event with relevant user data extracted from Telegram’s initData when users enter your Telegram Mini App. This streamlined process ensures that every event captured is already associated with the user’s profile, providing you with a comprehensive view of user activities without additional coding.

​
TON Wallet Integration

Similarly, when users connect their TON Wallet through TON Connect, the SDK automatically attaches the wallet address to the event data. This allows for seamless tracking of user interactions related to their wallet activities. In order to track TON related operations, such as wallet connections, signed transactions etc, you should use @tonconnect/ui or @tonconnect/ui-react. When these libs are detected, Telemetree will automatically log on-chain events.

​
Event Tracking

With Telemetree’s React SDK, tracking events is straightforward. You can monitor user interactions, like button clicks or page views, to understand how users engage with your app.

​
Step-by-step setup

  1. Import the Hook: First, import the useTWAEvent hook in the component where you want to track events.
  2. Initialize the Event Builder: Within your component, initialize the event builder.
  3. Track an Event: Use the track method to send an event. Here’s how to track a button-click event:
  4. Attach the Handler: Attach the handleButtonClick function to the onClick handler of your button. 
import { useTWAEvent } from '@tonsolutions/telemetree-react';

const eventBuilder = useTWAEvent();

const handleButtonClick = () => {
    eventBuilder.track('Button Clicked', {
    label: 'Subscribe Button', // Additional info about the button
    category: 'User Engagement', // Categorize the event
    });
};

<button onClick={handleButtonClick}>Subscribe</button>

​
Data Enrichment

User Events: When a user performs an action within your Mini App, the event is automatically tagged with their Telegram account data. 
// Event tracking with automatic user data attachment
eventBuilder.track('Action', { /* event-specific data */ });
// User data from Telegram is automatically included
Wallet Events: For financial transactions or wallet interactions, the SDK will enrich the event with the user’s wallet information. 
// Event tracking with automatic wallet data attachment
eventBuilder.track('Transaction', { amount: value });
// Wallet address and provider data is automatically included

​
Common Issues and Troubleshooting

SDK Initialization Errors:
  1. Ensure that you’ve correctly installed the SDK via npm or yarn and that you’re importing it as shown in the documentation.
  2. Verify that your project ID and API key are correct and that you have internet connectivity.
Event Tracking Not Working:
  1. Check that the TwaAnalyticsProvider is properly wrapped around your app’s root component.
  2. Confirm that you’re using the track method correctly with the necessary parameters.
Nextjs: Telegram Webapp is not loaded: Due to Nextjs caching logic it by design prevents Telegram JS script (https://telegram.org/js/telegram-web-app.js) from working correctly. In this case you have to use a Telegram SDK. This will solve the issue. Here is the Telemetree boilerpate app using SDK. Incorrect User or Wallet Data:
  1. Make sure that the initData from Telegram is correctly parsed and passed to the event tracking methods.
  2. Double-check the wallet connection logic and ensure that the address is being updated only when it changes.