Note
@tips_web_app_bot β a Mini App that provides a demonstration of the process of paying a tip to a waiter by QR code or waiter ID. The user is offered to choose the currency, calculate the tip amount - a fixed amount or a percentage of the bill and pay through the payment system. The user can also view the history of tips left.
- π
πΌ Developed from scratch a simple set of UI with @tma.js/sdk
- π³ Integration with Telegram payments
- π Support for multiple entry points: Main Bot Button, Inline Button, Direct Link, Direct Link with startapp parameter
- React + Typescript + SCSS Modules
- Vite
- Feature-sliced design as a project architecture
- Axios + @tanstack/react-query
- React-router-dom
- Developed from scratch a simple set of UI with @tma.js/sdk
- Eruda for debug in development mode, Sentry in production mode
The client part is built based on the Feature-Sliced design (FSD) architectural methodology. Within this methodology, the project consists of 6 slices:
-
app β Π½app-wide settings, styles and providers
- hocks β providers needed for applications to work, for example
BrowserRouter
,QueryClientProvider
- styles β global application styles
- index.tsx β entry point to the application where providers are compiled, styles and helper (sentry, eruda) are connected
- hocks β providers needed for applications to work, for example
-
pages β compositional layer to construct full pages from entities, features and widgets
-
widgets β compositional layer to combine entities and features into meaningful blocks
-
features β user interactions, actions that bring business value to the user
-
entities β business entities (tip, waiter)
- [entity]/ui β UI components that relate to our business entity
- [entity]/model β entity model: types and interfaces, state-manager, configs
- [entity]/api.ts β methods for interacting with the application backend
-
shared β reusable functionality, detached from the specifics of the project/business: UI kit, api, libs
This methodology provides low coupling of application components and high cohesion, which makes the application code more structured and scalable
Feature-sliced Design documentation
- Storybook available
- Implementation of @tma.js/sdk methods
- Telegram color palette support
- 13 basic components: Button, TextField, SegmentedControl, Page etc.
- Page component that allows you to control the TMA interface via props:
- backgroundColor - sets the background of the TMA page (event web_app_set_background_color)
- headerBackgroundColor - sets the background of the TMA header (event web_app_set_header_color)
- withCloseAppConfirmation - flag whether to ask for confirmation when closing the mini-application (event web_app_setup_closing_behavior)
- shouldExpanded - flag whether the mini-application should be expanded when the page is opened (event web_app_expand)
- withQuit - flag whether the backButton should be hidden, so that the user has the option to close the mini-application via the native cross in the application header (event web_app_setup_back_button)
- Components with support for haptic feedback: Button, Radio, ListItem, SegmentedControl (event web_app_trigger_haptic_feedback)
- @radix-ui/react-slot to merge component props with an immediate child element
UI kit is MVP, was built as part of Telegram Mini App Contest 2023 hackathon, components may contain bugs and errors
- node js 16.15.0+
- yarn 1.22.18+
Create the .env
file in the client side directory of the project and specify values for the following variables:
Variable Name | Required | Description | Example |
---|---|---|---|
VITE_API_URL |
True | Backend url with prefix /api | https://my-server.com/api |
VITE_SENTRY |
False | Sentry DSN | https://fw89ew89g7g8ew7g8we8@k3940287.ingest.sentry.io/234234543635523 |
- Move to the /client directory
cd client
- Run the
yarn install
command to install the project dependencies - To start the application in development mode, run the
yarn dev
command. - To build the project in production mode, run the
yarn build
command. - To build the project in development mode, run the
yarn build:dev
command.
After building the project, a /dist directory with the project code will be generated in the root. You can use any static hosting service, such as Vercel or Github Pages, for deployment.
- Fastify + Typescript
- MSQL + TypeORM
- node-telegram-bot-api
- node js 16.15.0+
- yarn 1.22.18+
- MySQL 8+
- Create a bot via @BotFather and get the token
- Get a test token for payments: instructions
Create an .env
file in the server-side directory and specify values for the following variables:
Variable Name | Required | Description | Example |
---|---|---|---|
TG_TOKEN |
True | Telegram BOT token | |
TG_PAYMENT_TOKEN |
True | Telegram BOT Payment token | |
TG_BOT_NAME |
True | Telegram BOT username (t.me/USERNAME) | tips_web_app_bot |
TG_BOT_APP_NAME |
True | Telegram Mini App name (t.me/username/APP_NAME) | tip |
TG_BOT_QR_URL |
True | Link to the image that the bot will send to the user when sending the /qr command | |
HOST |
True | localhost | |
DOMAIN |
True | Application domain, used for webhook (without last slash) | https://my-server.com |
PORT |
True | Port | |
DB_HOST |
True | Database host | |
DB_PORT |
True | Database port | |
DB_USER |
True | Database user | |
DB_PASSWORD |
True | Database password | |
DB_DATABASE |
True | Database name |
- Move to the /server directory
cd server
- Run the
yarn install
command to install the project dependencies - To start the application in development mode, run the
yarn dev
command. - To build the project in production mode, run the
yarn build
command, then run theyarn start
command to start the project.
Sentry allows you to remotely monitor bugs in frontend applications written in JavaScript. If your frontend application crashes, Sentry automatically sends error information to the remote Sentry server.
However, in addition to error information, Sentry can also log the user's secret data - hash signature of startup parameters. If the backend does not check the auth_date parameter, then knowing the user's signature, an attacker can open the mini-application on behalf of other users.
To prevent this, it is necessary to filter the data before logging the error in Sentry DSN. This can be done using the Sentry.beforeSend method.
In addition to filtering data, you can create your own Sentry context, for example, one that stores user information obtained from launch-params.
AS IS | TO BE |
---|---|
Sentry stores the tgWebAppData, along with a hash parameter for authorization on the backend | Sentry does not save the #hash of the request |
Initially, there is no user information available in a convenient way | Only useful information about the user (from launch params) is displayed in a convenient way |
Example |
While developing Telegram Mini App, you may need to debug on a real device. Eruda, a mobile developer console, can help you with that
Add a viewport tag to display the interface correctly on smartphones
<meta
name="viewport"
content="width=device-width, initial-scale=1, shrink-to-fit=no, user-scalable=no, viewport-fit=cover"
/>
To improve UX, you can disable text selection in the application, leaving the ability to select only the necessary elements - input, textarea.
*:not(input):not(textarea),
::after,
::before {
-moz-user-select: none;
-webkit-user-select: none;
-ms-user-select: none;
user-select: none;
}
Telegram Api
Bot Payments Api
Introducing into Telegram Mini Apps
Documentation @tma-js
This project is licensed under the MIT - see the LICENSE file for details