EN | RU

---

Tips — Telegram Mini App Example

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.

🔥 Features

• 💅🏼 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
  

---

📋 Table of contents

1. Client side
   1. Tech Stack and features
   2. Frontend architecture
   3. UI kit
   4. Build and run
2. Server side
   1. Tech Stack and features
   2. Build and run
3. Tips for Telegram Mini Apps
4. Learn More
5. License

---

⭐️ Client side

Tech Stack and features

• 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

Frontend architecture

The client part is built based on the Feature-Sliced design (FSD) architectural methodology. Within this methodology, the project consists of 6 slices:

1. app — нapp-wide settings, styles and providers

   1. hocks — providers needed for applications to work, for example BrowserRouter, QueryClientProvider
   2. styles — global application styles
   3. index.tsx — entry point to the application where providers are compiled, styles and helper (sentry, eruda) are connected

2. pages — compositional layer to construct full pages from entities, features and widgets

3. widgets — compositional layer to combine entities and features into meaningful blocks

4. features — user interactions, actions that bring business value to the user

5. entities — business entities (tip, waiter)

   1. [entity]/ui — UI components that relate to our business entity
   2. [entity]/model — entity model: types and interfaces, state-manager, configs
   3. [entity]/api.ts — methods for interacting with the application backend

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

UI kit

Features

• 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

Build and run

Requirements:

• node js 16.15.0+
• yarn 1.22.18+

Environment variables:

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://[email protected]/234234543635523

Starting the project

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

Project Deployment

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.

⭐️ Server side

Tech Stack and features

• Fastify + Typescript
• MSQL + TypeORM
• node-telegram-bot-api

Build and run

Requirements:

• node js 16.15.0+
• yarn 1.22.18+
• MySQL 8+

Before installing:

• Create a bot via @BotFather and get the token
• Get a test token for payments: instructions

Environment variables:

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

Starting the project

• 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 the yarn start command to start the project.

---

💻 Tips for Telegram Mini Apps

Sentry and sensitive user data

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

Mobile debugging

While developing Telegram Mini App, you may need to debug on a real device. Eruda, a mobile developer console, can help you with that

Viewport settings

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"
/>

Disable text selection

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;
}

🛠 Learn More

Telegram Api
Bot Payments Api
Introducing into Telegram Mini Apps
Documentation @tma-js

License

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