React
Getting started
System Requirements
- A package manager such as npm (version 6 or newer) or yarn
- A Telegram Mini App project set up with React
Installation
Install Telemetree React SDK using npm or yarn
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
- Add the script to your
index.html
file in the<head>
:
<script src="https://telegram.org/js/telegram-web-app.js"></script>
- Import the SDK: Start by importing the Telemetree provider into your main application file, typically
App.js
. - Wrap Your Application: Use the
TwaAnalyticsProvider
component to wrap your application’s root component. This enables analytics tracking throughout your app - 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.
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.
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
- Import the Hook: First, import the
useTWAEvent
hook in the component where you want to track events. - Initialize the Event Builder: Within your component, initialize the event builder.
- Track an Event: Use the track method to send an event. Here’s how to track a button-click event:
- Attach the Handler: Attach the handleButtonClick function to the onClick handler of your 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:
- Ensure that you’ve correctly installed the SDK via npm or yarn and that you’re importing it as shown in the documentation.
- Verify that your project ID and API key are correct and that you have internet connectivity.
Event Tracking Not Working:
- Check that the
TwaAnalyticsProvider
is properly wrapped around your app’s root component. - Confirm that you’re using the
track
method correctly with the necessary parameters.
Incorrect User or Wallet Data:
- Make sure that the initData from Telegram is correctly parsed and passed to the event tracking methods.
- Double-check the wallet connection logic and ensure that the address is being updated only when it changes.