Guides

React SDK

Suggest Edits

📘

React resources

Github | NPM

📘

Bundle size

Search for the package on bundle phobia to view its size and other details. For example you can search @tonsolutions/telemetree-react!

Introduction

Welcome to Telemetree's React SDK, the dedicated solution for integrating powerful analytics into your Telegram Mini Apps. Our SDK is designed to be lightweight and easy to implement, providing you with real-time insights into how users interact with your application. With our React SDK, you can effortlessly track user events, understand user behaviors, and optimize your app performance based on data-driven insights.

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:

To install the React SDK, open your terminal, navigate to your project directory, and run one of the following commands:

Using npm:

npm install @tonsolutions/telemetree-react --save

Using yarn:

yarn add @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. Import the SDK: Start by importing the Telemetree provider into your main application file, typically App.js.
import { TwaAnalyticsProvider } from '@tonsolutions/telemetree-react';
  1. Wrap Your Application: Use the TwaAnalyticsProvider component to wrap your application's root component. This enables analytics tracking throughout your app.
export function App() {
  return (
    <TwaAnalyticsProvider
      projectId='YOUR_PROJECT_ID'
      apiKey='YOUR_API_KEY'
      appName='YOUR_APPLICATION_NAME'
    >
      {/* Rest of your app components */}
    </TwaAnalyticsProvider>
  );
}
  1. 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.

Basic 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.

Tracking User Events

Step-by-step setup

  1. Import the Hook: First, import the useTWAEvent hook in the component where you want to track events.
import { useTWAEvent } from '@tonsolutions/telemetree-react';
  1. Initialize the Event Builder: Within your component, initialize the event builder.
const eventBuilder = useTWAEvent();
  1. Track an Event: Use the track method to send an event. Here's how to track a button-click event:
const handleButtonClick = () => {
  eventBuilder.track('Button Clicked', {
    label: 'Subscribe Button', // Additional info about the button
    category: 'User Engagement', // Categorize the event
  });
  // ... rest of your click handling logic
};
  1. Attach the Handler: Attach the handleButtonClick function to the onClick handler of your button.
<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

Troubleshooting and Support

Even with the most robust systems, developers may encounter unexpected behavior or issues. The following guidelines are designed to help you troubleshoot common problems and access support resources for the Telemetree React SDK.

Common Issues and Solutions

  1. 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.
  2. 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.
  3. 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.

Debugging Tips

  • Use browser developer tools to monitor network requests and confirm that events are being sent to Telemetree.
  • Add console logs in your event handling functions to verify that events are being triggered as expected.
  • Whenever there's an issue with sending events, the library will print it out into the console. Review the console for any warnings or errors that could provide more information about issues.

Getting Support

If you're unable to resolve issues with the information provided above, Telemetree offers several support channels:

  • Documentation: Review detailed guides and API references for additional information.
  • Community Forums: Engage with other developers and the Telemetree team on community forums for help with common challenges.
  • Email Support: Reach out to our support team via email for direct assistance at [email protected]

Staying Updated

  • Keep your SDK version up to date to benefit from the latest fixes and improvements.
  • Follow the TON Solutions blog or subscribe to the newsletter for announcements about new features and updates.

Release Notes

Coming soon

Updated 4 months ago