На главную

DF-ВЕБ-031 · Контент и сайты

HTML-виджеты в Telegram: проверки перед встраиванием

Редакция Deskforge · 14 ноября 2026 · 5 мин чтения
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 — только при запуске из меню вложений. Условный пример: если виджет открывается из меню вложений, чтение буфера обмена по клику допустимо; при запуске по ссылке тот же код вернёт отказ.

Пройдите этот список до публикации, а не после первой жалобы.

Структура и полнота шагов проверены локально; фактические утверждения сверены по первоисточникам ниже.

Источники

Назад