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

Якщо ви хоч раз намагалися створити Telegram Web App (TWA) без жодного шару абстракції — ви знаєте, що це таке. Пряма робота з window.Telegram.WebApp технічно працює, але код виходить громіздким, поведінка відрізняється залежно від платформи, а про типобезпеку можна забути. Саме це і вирішує @twa-dev/sdk.

У цій статті розберемо, що насправді робить SDK, як його встановити, які ключові можливості він надає і з якими проблемами найчастіше стикаються розробники. Без зайвої води — лише те, що потрібно, щоб запустити продукт.

Що таке @twa-dev/sdk?

@twa-dev/sdk — це відкритий TypeScript/JavaScript-пакет, який обгортає JavaScript API Telegram Web App. Його підтримує спільнота, а вихідний код знаходиться на GitHub.

Нативний API Telegram Web App доступний як глобальний об'єкт, який Telegram вбудовує у ваш webview. Він працює, але створювався під браузерне середовище, а не під сучасні TypeScript-фронтенди. @twa-dev/sdk дає вам:

• Повні TypeScript-типи (більше не потрібно гадати, які поля існують)

• Реактивні обгортки навколо Telegram-подій

• Однакову поведінку на iOS, Android і Telegram Desktop

• Зручніший досвід розробки з нормальними імпортами модулів

Коротко: менше шаблонного коду, а більшість помилок ловиться на етапі компіляції — а не о другій ночі, коли користувач пишає про краш.

Встановлення та налаштування @twa-dev/sdk

Почати роботу дуже просто. Встановіть пакет через npm або yarn:

npm install @twa-dev/sdk
# або
yarn add @twa-dev/sdk

npm install @twa-dev/sdk
# або
yarn add @twa-dev/sdk

npm install @twa-dev/sdk
# або
yarn add @twa-dev/sdk

Потім імпортуйте його у свій застосунок. SDK експортує об'єкт WebApp за замовчуванням, який повторює API Telegram Web App — але з типами та деякими зручними покращеннями:

import WebApp from '@twa-dev/sdk';

WebApp.ready(); // Повідомляємо Telegram, що застосунок завантажено
console.log(WebApp.initDataUnsafe.user); // Типізований об'єкт користувача

import WebApp from '@twa-dev/sdk';

WebApp.ready(); // Повідомляємо Telegram, що застосунок завантажено
console.log(WebApp.initDataUnsafe.user); // Типізований об'єкт користувача

import WebApp from '@twa-dev/sdk';

WebApp.ready(); // Повідомляємо Telegram, що застосунок завантажено
console.log(WebApp.initDataUnsafe.user); // Типізований об'єкт користувача

Для базового старту цього достатньо. Жодних конфігураційних файлів, жодних зайвих ритуалів. Використовуєте React, Vue або Svelte — просто підключаєте й працюєте.

Одна важлива деталь

SDK розрахований на роботу всередині Telegram WebView. Якщо ви спробуєте запустити застосунок у звичайному браузері (наприклад, під час локальної розробки), window.Telegram.WebApp просто не існуватиме, і ви отримаєте помилки. Зазвичай це вирішують або мокуванням об'єкта локально, або використанням тестового середовища для Telegram Міні-застосунків.

Використовуйте WebApp.isExpanded, WebApp.platform та перевірки середовища, щоб захистити платформо-специфічну логіку під час розробки.

Ключові можливості, які ви будете використовувати постійно

Головна кнопка та кнопка «Назад»

У Telegram Web Apps є нативні елементи UI — Головна кнопка (велика кнопка внизу) та Кнопка «Назад» (у заголовку). Керувати ними через сирий API незручно. З @twa-dev/sdk все виглядає так:

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

WebApp.BackButton.show();
WebApp.BackButton.onClick(() => router.back());

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

WebApp.BackButton.show();
WebApp.BackButton.onClick(() => router.back());

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

WebApp.BackButton.show();
WebApp.BackButton.onClick(() => router.back());

Чисто, типізовано, передбачувано. У будь-якому більш-менш серйозному міні-застосунку ви будете використовувати це постійно.

Init Data та автентифікація користувачів

Коли користувач відкриває ваш TWA, Telegram передає initData — рядок із даними про користувача, контекстом чату та хешем, який можна перевірити на сервері. SDK розбирає це за вас:

const user = WebApp.initDataUnsafe.user;
// { id: 123456789, first_name: 'Олекс', username: 'alex_dev', ... }

const user = WebApp.initDataUnsafe.user;
// { id: 123456789, first_name: 'Олекс', username: 'alex_dev', ... }

const user = WebApp.initDataUnsafe.user;
// { id: 123456789, first_name: 'Олекс', username: 'alex_dev', ... }

Завжди перевіряйте initData на сервері — ніколи не довіряйте лише клієнту. Хеш підписується токеном вашого бота, тому ви можете верифікувати його через HMAC-SHA256. Саме так автентифікуються користувачі — без паролів і OAuth-потоків.

Тактильний зворотний зв'язок (Haptic Feedback)

Дрібниця, яка суттєво впливає на UX. SDK надає WebApp.HapticFeedback з трьома методами:

• impactOccurred('light' | 'medium' | 'heavy' | 'rigid' | 'soft')

• notificationOccurred('error' | 'success' | 'warning')

• selectionChanged()

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

Тема та кольорові змінні

Telegram передає CSS-змінні для поточної теми користувача (світла/темна, кастомні кольори). SDK надає зручний доступ до них через WebApp.themeParams, тому ви можете будувати UI, який виглядає органічно незалежно від теми Telegram у користувача.

@twa-dev/sdk проти сирого API Telegram Web App: у чому реальна різниця?

Чесно? Для невеликих проєктів можна обійтися сирим API. Глобальний об'єкт Telegram.WebApp добре задокументований і не потребує залежностей.

Але щойно проєкт переростає один файл, сирий API починає гальмувати розробку:

• Без TypeScript-типів постійно доводиться використовувати any і стикатися з несподіванками у runtime

• Обробка подій ручна й легко призводить до витоків (якщо забути видалити слухачів)

• Кросплатформові відмінності (iOS vs. Android vs. Desktop) проявляються як баги в продакшені, а не помилки компіляції

@twa-dev/sdk — правильний вибір за замовчуванням для будь-якого серйозного проєкту. Вартість залежності мінімальна. Покращення в досвіді розробки — реальне.

Типові помилки при розробці Telegram Web Apps

Навіть з хорошим SDK розробники наступають на одні й ті самі граблі. Ось на що варто звернути увагу:

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

• Ігнорування змін viewport. Клавіатура з'являється — viewport зменшується. Якщо ви не слухаєте WebApp.onEvent('viewportChanged', ...), верстка буде ламатися на мобільних пристроях.

• Довіра до initDataUnsafe. Назва говорить сама за себе. Завжди верифікуйте рядок initData на сервері, перш ніж довіряти будь-яким даним користувача.

• Хардкод кольорів замість тематичних змінних. Ваш застосунок виглядатиме зламаним у темному режимі або для користувачів із кастомними темами Telegram.

• Ігнорування WebApp.expand(). За замовчуванням міні-застосунок відкривається в частковому вигляді. Викликайте WebApp.expand(), якщо потрібен повноекранний режим — більшість застосунків виграє від цього.

Також раджу прочитати: практики безпеки для Telegram Міні-застосунків — особливо якщо ваш застосунок обробляє дані користувачів або платежі.

Коли Telegram Web Apps мають сенс для продажів і CRM-процесів

Ось де починається справді цікаве з бізнесової точки зору. Telegram Web Apps — це не лише ігри та утиліти. Їх дедалі частіше використовують для вбудовування CRM-інтерфейсів, форм захоплення лідів, онбордингових потоків і дашбордів прямо всередині Telegram-чатів.

Уявіть: ви просите потенційного клієнта відкрити окрему вкладку браузера, зареєструватися й заповнити форму. А тепер порівняйте це з кнопкою в Telegram-повідомленні, яка одразу відкриває міні-застосунок — із заздалегідь заповненими даними Telegram-акаунта, без жодного входу.

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

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

Підсумок

Використовуйте @twa-dev/sdk, якщо ви будуєте щось серйозніше за вікендний прототип. Він дає вам типи, зручнішу обробку подій і кросплатформену стабільність — і все це практично безкоштовно.

Ваш стартовий чеклист:

1. Встановіть @twa-dev/sdk і замініть прямі виклики window.Telegram.WebApp

2. Викликайте WebApp.ready() якомога раніше

3. Викликайте WebApp.expand(), якщо потрібен повноекранний режим

4. Завжди верифікуйте initData на сервері

5. Використовуйте тематичні змінні, щоб UI не виглядав зламаним у темному режимі

6. Тестуйте на реальних пристроях (iOS і Android), а не лише в браузері

Це основа. Будуйте на ній.