@twa-dev/sdk: Як створювати Telegram Mini Apps, які справді працюють

Якщо ви розробляєте Telegram Міні-застосунок і читаєте офіційну документацію, то помітите, що там згадується сирий об'єкт window.Telegram.WebApp. Він працює — але громіздкий, не типізований і незручний у сучасних фреймворках. Саме тут на допомогу приходить @twa-dev/sdk.

Пакет @twa-dev/sdk — це неофіційна, але широко використовувана TypeScript-обгортка навколо Telegram Web App API. Вона дає повну типобезпеку, чистіший синтаксис і набагато приємніший досвід розробки — без жодних реальних накладних витрат. Якщо ви серйозно беретесь за Telegram Міні-застосунки, це саме той SDK, який вам потрібен.

Що насправді робить @twa-dev/sdk

Офіційний Telegram Web App API доступний через глобальний JavaScript-об'єкт, який Telegram-клієнт додає автоматично. Для простих скриптів це нормально, але щойно ви починаєте працювати в React, Vue чи Svelte-проєкті — робота з сирими глобальними об'єктами швидко перетворюється на хаос.

@twa-dev/sdk огортає цей глобальний об'єкт у типізований модуль, який можна імпортувати. Ось що ви отримуєте відразу:

• Повна типізація TypeScript — автодоповнення для кожного методу, події та властивості

• Чистіші імпорти — використовуйте import WebApp from '@twa-dev/sdk' замість звернення до window.Telegram.WebApp

• Сумісність з реактивними фреймворками — добре працює з React, Vue та іншими компонентними фреймворками

• Актуальність — пакет відстежує офіційний Telegram API, тому вам не доведеться самостійно підтримувати власні оголошення типів

Це тонкий прошарок. Він не додає магії і не приховує основний API. Сприймайте його як строго типізований інтерфейс, а не як фреймворк.

Як встановити та налаштувати

Встановлення займає приблизно 30 секунд:

npm install @twa-dev/sdk

npm install @twa-dev/sdk

npm install @twa-dev/sdk

Потім імпортуйте там, де потрібно:

import WebApp from '@twa-dev/sdk'

import WebApp from '@twa-dev/sdk'

import WebApp from '@twa-dev/sdk'

Все. Тепер у вас є доступ до повного Telegram Web App API — дані користувача, теми оформлення, кнопки, попапи, тактильний відгук тощо.

Мінімальний робочий приклад

Ось простий React-компонент, який отримує дані поточного користувача і сигналізує, що застосунок готовий:

import WebApp from '@twa-dev/sdk'
import { useEffect } from 'react'

export default function App() {
  useEffect(() => {
    WebApp.ready()
    console.log(WebApp.initDataUnsafe.user)
  }, [])

  return <div>Привіт, {WebApp.initDataUnsafe.user?.first_name}</div>
}

import WebApp from '@twa-dev/sdk'
import { useEffect } from 'react'

export default function App() {
  useEffect(() => {
    WebApp.ready()
    console.log(WebApp.initDataUnsafe.user)
  }, [])

  return <div>Привіт, {WebApp.initDataUnsafe.user?.first_name}</div>
}

import WebApp from '@twa-dev/sdk'
import { useEffect } from 'react'

export default function App() {
  useEffect(() => {
    WebApp.ready()
    console.log(WebApp.initDataUnsafe.user)
  }, [])

  return <div>Привіт, {WebApp.initDataUnsafe.user?.first_name}</div>
}

WebApp.ready() повідомляє Telegram, що застосунок завантажився і індикатор завантаження можна приховати. Завжди викликайте це на початку. Якщо пропустити — користувачі бачитимуть крутилку вічно.

Функції, які ви будете використовувати найчастіше

Telegram Web App API доволі великий. Ось частини, до яких ви будете звертатись у майже кожному проєкті:

MainButton

MainButton — це помітна CTA-кнопка, яка з'являється внизу Міні-застосунку. Ви повністю керуєте нею:

WebApp.MainButton.setText('Підтвердити замовлення')
WebApp.MainButton.show()
WebApp.MainButton.onClick(() => handleSubmit())

WebApp.MainButton.setText('Підтвердити замовлення')
WebApp.MainButton.show()
WebApp.MainButton.onClick(() => handleSubmit())

WebApp.MainButton.setText('Підтвердити замовлення')
WebApp.MainButton.show()
WebApp.MainButton.onClick(() => handleSubmit())

Це один із найпомітніших елементів інтерфейсу в Міні-застосунку. Використовуйте її для основних дій — оформлення, підтвердження, відправки — і ховайте, коли вона не стосується поточного екрану.

initDataUnsafe

Тут зберігаються дані поточного користувача Telegram: ID, ім'я, username, код мови та наявність Premium. Вона «небезпечна» тому, що є клієнтською — завжди перевіряйте її на сервері за допомогою initData і токена бота, перш ніж довіряти їй у чомусь важливому.

HapticFeedback

Дрібна деталь із великим ефектом. Тактильний відгук робить застосунок по-справжньому нативним на мобільних пристроях:

WebApp.HapticFeedback.impactOccurred('medium')
WebApp.HapticFeedback.notificationOccurred('success')

WebApp.HapticFeedback.impactOccurred('medium')
WebApp.HapticFeedback.notificationOccurred('success')

WebApp.HapticFeedback.impactOccurred('medium')
WebApp.HapticFeedback.notificationOccurred('success')

Тема і кольорова схема

Telegram передає поточну тему користувача (світла/темна) і кольорові змінні. Використовуйте WebApp.colorScheme та CSS-змінні, які додає Telegram (--tg-theme-bg-color тощо), щоб відповідати нативному вигляду без жодного додаткового налаштування.

sendData і close

WebApp.sendData() відправляє рядок даних назад вашому боту. Використовуйте це для простих відправок форм, де бот має відреагувати на введення користувача. WebApp.close() закриває Міні-застосунок — викликайте після завершення сценарію.

@twa-dev/sdk проти сирого window.Telegram.WebApp — що обрати?

Чесно? Використовуйте @twa-dev/sdk для будь-якого проєкту, де більше одного розробника або складність виходить за межі вихідного вікенду.

• Якщо ви прототипуєте маленький скрипт — сирий API підійде

• Якщо ви будуєте на React, Vue або будь-якому TypeScript-проєкті — використовуйте SDK

• Якщо хочете ловити баги на етапі компіляції, а не в рантаймі — використовуйте SDK

Сирий API нікуди не зникне. Але SDK позбавляє вас необхідності писати власні оголошення типів, уникати друкарських помилок у назвах методів і тих багів, які з'являються лише на пристрої користувача о другій ночі.

Щоб глибше розібратися, як працює основний API і що можна на ньому побудувати, читайте нашу статтю про Telegram Mini App API.

Безпека: не довіряйте initDataUnsafe на сервері

Це помилка, на якій спотикаються більшість розробників-початківців. initDataUnsafe — це дані, надані клієнтом. Їх можна підробити. Якщо ви використовуєте їх для ідентифікації користувачів на бекенді — ви будуєте на піску.

Правильний підхід:

1. Надішліть сирий рядок WebApp.initData на сервер (не initDataUnsafe)

2. На сервері перевірте HMAC-підпис за допомогою токена вашого бота

3. Довіряйте даним користувача лише після успішної перевірки

Telegram описує алгоритм верифікації в офіційній документації. Це нескладно — кілька рядків на будь-якій бекенд-мові. Не пропускайте цей крок. Щоб дізнатися більше про безпеку Міні-застосунків, читайте нашу статтю про безпеку Telegram Mini Apps.

Розробка продакшн-застосунків для Telegram

Коли ваш Міні-застосунок готовий, наступний виклик — підключити його до реальних продажів і бізнес-процесів. Саме тут проявляється різниця між «крутим демо» і «справді корисним інструментом».

Якщо ви будуєте Telegram-орієнтований продаж або CRM-процес — а не разовий Міні-застосунок — зверніть увагу на CRMChat API. Він дозволяє налаштувати кастомні інтеграційні потоки для Telegram: надсилати ліди з вашого Міні-застосунку в CRM-пайплайн, запускати аутріч-послідовності або синхронізувати дані розмов — без необхідності будувати всю інфраструктуру з нуля.

Щоб краще зрозуміти, як Telegram вписується в сучасний процес продажів, ця стаття про CRM-інтеграцію з Telegram добре охоплює практичну сторону питання.

Коротко

@twa-dev/sdk — це правильний вибір за замовчуванням для всіх, хто розробляє Telegram Міні-застосунки на сучасному JS/TS-стеку. Встановіть, імпортуйте, викликайте WebApp.ready() на початку, перевіряйте initData на сервері і використовуйте MainButton для основних CTA.

API великий, але добре задокументований. Не потрібно вивчати все одразу. Починайте з initDataUnsafe, MainButton і sendData — це покриє 80% того, що більшість Міні-застосунків насправді й робить.