React-telegram-miniapp NPM

React Telegram MiniApp

Overview

React Telegram MiniApp is a developer-centric library tailored for seamless integration of Telegram Mini Apps into React and Next.js projects. It provides a rich set of hooks, components, and utilities to work with the Telegram WebApps API, enabling the creation of highly interactive experiences within Telegram.

Features

🌟 TelegramProvider: Efficiently manage the Telegram WebApp context state across your React components.
🔄 Custom Hooks: Simplified handling of Telegram WebApp events like theme changes, button interactions, and more.
🔐 Data Validation: Securely validate data received from the Telegram WebApp on your backend.
🛠️ TypeScript Support: Fully typed, ensuring a robust and type-safe development experience.
🎛️ Custom Script Loader: Automatically loads the Telegram WebApp script based on the environment.

Installation

Install the package using your preferred package manager:

npm install react-telegram-miniapp
# or
yarn add react-telegram-miniapp
# or
pnpm install react-telegram-miniapp

Getting Started

1. Wrap Your Application with `TelegramProvider`

Wrap your main application component with TelegramProvider to initialize the Telegram WebApp context.

import React from 'react';
import { TelegramProvider } from 'react-telegram-miniapp';

const MyApp = ({ Component, pageProps }) => (
  <TelegramProvider>
    <Component {...pageProps} />
  </TelegramProvider>
);

export default MyApp;

2. Utilize Hooks to Handle Telegram Events

Leverage the provided hooks to manage various Telegram WebApp events:

import React from 'react';
import { useThemeChanged, useMainButtonClicked } from 'react-telegram-miniapp';

const MyComponent = () => {
  useThemeChanged(() => {
    console.log("Theme changed!");
  });

  useMainButtonClicked(() => {
    console.log("Main button clicked!");
  });

  return <h1>Hello, Telegram User!</h1>;
};

export default MyComponent;

3. Validate Telegram WebApp Data on the Backend

Securely validate the data received from the Telegram WebApp using the validateWebAppData utility:

import { validateWebAppData } from 'react-telegram-miniapp';

const botToken = 'YOUR_BOT_TOKEN';

app.post('/validate-webapp-data', (req, res) => {
  const { initData } = req.body;

  const validationResult = validateWebAppData(initData, botToken);

  if (validationResult.isValid) {
    res.status(200).send('Data is valid');
  } else {
    res.status(400).send(`Invalid data: ${validationResult.reason}`);
  }
});

Documentation

Components

Component	Description	Props
`TelegramProvider`	Initializes and manages the Telegram WebApp context.	`children`: ReactNode - Components to wrap.

Hooks

Hook	Description	Example Usage
`useThemeChanged`	Handles the `themeChanged` event.	`useThemeChanged(() => { console.log("Theme changed!"); });`
`useMainButtonClicked`	Handles the `mainButtonClicked` event.	`useMainButtonClicked(() => { console.log("Main button clicked!"); });`
`useViewportChanged`	Handles the `viewportChanged` event.	`useViewportChanged((event) => { console.log("Viewport changed:", event); });`
`useBackButtonClicked`	Handles the `backButtonClicked` event.	`useBackButtonClicked(() => { console.log("Back button clicked!"); });`
`useSettingsButtonClicked`	Handles the `settingsButtonClicked` event.	`useSettingsButtonClicked(() => { console.log("Settings button clicked!"); });`
`useInvoiceClosed`	Handles the `invoiceClosed` event.	`useInvoiceClosed((event) => { console.log("Invoice closed:", event); });`
`usePopupClosed`	Handles the `popupClosed` event.	`usePopupClosed((event) => { console.log("Popup closed:", event); });`
`useQrTextReceived`	Handles the `qrTextReceived` event.	`useQrTextReceived((event) => { console.log("QR text received:", event.data); });`
`useScanQrPopupClosed`	Handles the `scanQrPopupClosed` event.	`useScanQrPopupClosed(() => { console.log("QR scan popup closed!"); });`
`useClipboardTextReceived`	Handles the `clipboardTextReceived` event.	`useClipboardTextReceived((event) => { console.log("Clipboard text received:", event.data); });`
`useWriteAccessRequested`	Handles the `writeAccessRequested` event.	`useWriteAccessRequested((event) => { console.log("Write access requested:", event.status); });`
`useContactRequested`	Handles the `contactRequested` event.	`useContactRequested((event) => { console.log("Contact requested:", event.status); });`
`useBiometricManagerUpdated`	Handles the `biometricManagerUpdated` event.	`useBiometricManagerUpdated(() => { console.log("Biometric manager updated!"); });`
`useBiometricAuthRequested`	Handles the `biometricAuthRequested` event.	`useBiometricAuthRequested((event) => { console.log("Biometric auth requested:", event.isAuthenticated); });`
`useBiometricTokenUpdated`	Handles the `biometricTokenUpdated` event.	`useBiometricTokenUpdated((event) => { console.log("Biometric token updated:", event.isUpdated); });`

Utilities

`validateWebAppData`

Description: Validates the integrity of data received from the Telegram WebApp.
Parameters:
- initData: string - The data received from the WebApp.
- botToken: string - Your bot’s token.
Returns: { isValid: boolean, reason?: string }
Example Usage:

const validationResult = validateWebAppData(initData, botToken);

if (validationResult.isValid) {
  console.log("Data is valid");
} else {
  console.log("Invalid data:", validationResult.reason);
}

Advanced Usage

Centralized Event Management

To manage multiple Telegram WebApp events centrally, utilize a custom hook or context:

import { useGlobalEventManager } from 'react-telegram-miniapp';

const { registerEvent, unregisterEvent } = useGlobalEventManager();

useEffect(() => {
  const themeHandler = () => console.log('Theme changed!');
  registerEvent('themeChanged', themeHandler);

  return () => unregisterEvent('themeChanged', themeHandler);
}, [registerEvent, unregisterEvent]);

Customizing Event Handling

Tailor event handling with options like debounce, throttle, once, and debug:

useThemeChanged(() => {
  console.log('Theme changed!');
}, { debounce: 300, debug: true });

Debugging Tips

Enable Debug Mode: Pass { debug: true } to any hook to log detailed event information.
Inspect Validation Failures: When using validateWebAppData, check the reason to understand validation issues.

Contributing

We welcome contributions, issues, and feature requests! Check the issues page to see how you can help.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

Special thanks to the contributors and the Telegram team for their exceptional platform.

Developed by CodedPro

react telegram miniapp nextjs typescript telegram miniapp telegram webapp webapp

10 months ago

10 months ago

11 months ago

11 months ago