HTML-виджеты в Telegram: проверки перед встраиванием
- Какие данные виджета нельзя использовать без проверки на сервере
- Как убедиться, что страница и вложенный документ находятся в защищённом контексте
- Какие ограничения у sendData и как проверить данные на стороне получателя
- Чек-лист решений перед публикацией виджета
Виджет уже открывается в Telegram, кнопки нажимаются, данные приходят. Кажется, что осталось только выложить. А потом выясняется, что часть значений пришла из поля, которому доверять нельзя, вложенный документ открылся не в защищённом контексте, а кнопка отправки данных работает не при каждом способе запуска.
Ниже — порядок проверок до публикации: откуда берутся данные, в каком контексте открывается страница, что можно передать боту и какие вызовы допустимы. Это редакционный чек-лист Deskforge, а не отчёт об испытании продукта и не клиентский кейс: шаги нужно адаптировать к вашему виджету и способу запуска. Смежная тема — PWA-приложение из сайта, а варианты работ с сайтами и приложениями собраны на странице контента и сайтов.
Что проверить в источнике данных до отрисовки виджета
Первое решение — каким данным вы вообще доверяете. Документация Telegram Mini Apps прямо предупреждает: данные из поля initData нужно проверять на сервере бота до использования. Это относится к значениям, на которых строятся права доступа, идентификаторы и любые решения в интерфейсе.
Отдельно есть поле initDataUnsafe. Его название говорит само за себя: по документации этим данным доверять нельзя, а использовать их следует только после проверки данных из initData на сервере бота. На практике это значит, что обработчик не должен брать значения из initDataUnsafe и сразу подставлять их в логику.
Третья проверка — порядок подключения скрипта. Скрипт telegram-web-app.js размещается в теге head до любых других скриптов. Если он подключён позже, объект с методами может быть ещё не готов в момент, когда ваш код к нему обращается.
Проверить это можно так: откройте обработчик, который читает данные при загрузке, и проследите, откуда берётся каждое значение. Если источник — initDataUnsafe и при этом нет серверной проверки initData, это место для правки до публикации.
Защищённый контекст: как понять, что страница и вложенный документ ему соответствуют
Защищённый контекст — это условие, при котором браузер разрешает часть возможностей. По MDN, документ в iframe является защищённым контекстом, только если он доставлен по потенциально доверенному URL и сам встроен в защищённый контекст. Оба условия должны выполняться одновременно.
Пример из того же источника показывает, как это ломается: если документ верхнего уровня с http://example.com встраивает iframe с https://example.com, встроенный документ не является защищённым контекстом. То есть одного https у вложенной страницы недостаточно — важен и родительский документ.
Проверить собственный контекст страница может через свойство Window.isSecureContext. Это самый быстрый способ убедиться, что вы открыли виджет там, где ожидали, а не на тестовом стенде с другой схемой.
Есть и косвенный признак: регистрация service worker разрешена только в защищённых контекстах. Если ваш виджет опирается на service worker, отказ в регистрации — повод перепроверить, тот ли контекст вы получили, на который рассчитывали.
Передача данных из виджета: ограничения sendData и проверка на стороне получателя
Метод sendData передаёт боту служебное сообщение с данными длиной до 4096 байт и закрывает мини-приложение. Оба ограничения важны: и размер, и то, что после вызова виджет закрывается — сценарий с продолжением работы после отправки на этом методе не построить.
Второе ограничение — способ запуска. Метод sendData доступен только мини-приложениям, запущенным через кнопку клавиатуры. Если виджет открывается иначе, кнопка отправки данных просто не сработает, и это выяснится уже у пользователя.
Проверка объёма делается до публикации: измерьте длину строки данных и сравните с лимитом 4096 байт. Для кириллицы считайте байты, а не символы — строка из русских букв занимает больше места, чем кажется по длине.
На принимающей стороне тоже есть изменение, о котором стоит знать: сторонние получатели или обработчики данных от имени мини-приложений могут проверять эти данные, не зная токен бота приложения. Это снимает часть вопросов при передаче обработки внешнему сервису, но не отменяет самой проверки.
Обработка событий и вызовов, привязанных к действию пользователя
Часть методов Telegram разрешает вызывать только в ответ на действие пользователя. Для openLink условие сформулировано прямо: метод можно вызывать только в ответ на взаимодействие пользователя с интерфейсом мини-приложения — например, по клику внутри виджета или на основной кнопке.
Практический вывод: автозапуск openLink при загрузке страницы — не рабочая схема. Просмотрите места вызова и убедитесь, что каждое привязано к клику, а не к событию загрузки или таймеру.
У readTextFromClipboard ограничение двойное. Метод доступен только мини-приложениям, запущенным из меню вложений, и только в ответ на взаимодействие пользователя с интерфейсом. То есть даже правильный клик не поможет, если виджет открыт другим способом.
Здесь легко ошибиться в тестировании: на стенде, где виджет запускается удобным вам способом, чтение буфера обмена может работать, а в реальном сценарии запуска — нет. Проверяйте каждый метод в том способе запуска, в котором виджет увидит пользователь.
Чек-лист решений перед публикацией виджета
Соберём проверки в один проход. Данные: значения из initDataUnsafe не попадают в логику без проверки initData на сервере. Скрипт telegram-web-app.js стоит в head до остальных скриптов.
Контекст: window.isSecureContext на тестовом стенде подтверждает защищённый контекст, а схема URL вложенного документа и родительской страницы сверена по правилу MDN — оба документа должны быть в защищённом контексте.
Передача: sendData вызывается только там, где мини-приложение открыто кнопкой клавиатуры, а длина данных укладывается в 4096 байт. Получатель проверяет пришедшие данные, а не принимает их на веру.
События: openLink и readTextFromClipboard вызываются по клику, без автозапуска при загрузке, и readTextFromClipboard — только при запуске из меню вложений. Условный пример: если виджет открывается из меню вложений, чтение буфера обмена по клику допустимо; при запуске по ссылке тот же код вернёт отказ.
Пройдите этот список до публикации, а не после первой жалобы.
Структура и полнота шагов проверены локально; фактические утверждения сверены по первоисточникам ниже.