Skip to main content
Когда мини-приложение открывается на кастомной странице школы, Exode передаёт ему initData — строку с данными пользователя и школы, подписанную HMAC-SHA256 (аналог initData в Telegram Mini Apps). Проверив подпись на своём сервере, вы можете доверять этим данным и авторизовать пользователя без собственной регистрации.
Данные из postMessage-контекста (ctx.user) не подписаны и годятся только для отображения. Любая авторизация на вашем бэкенде должна опираться исключительно на проверенную initData.

Как это работает

  1. Exode открывает вашу страницу в iframe с адресом https://ваш-домен/…#exodeInitData=<строка>.
  2. Мини-приложение читает строку из fragment (retrieveInitData) и отправляет своему бэкенду.
  3. Бэкенд проверяет подпись секретом страницы (verifyInitData) и получает данные пользователя.
Секрет страницы выдаётся в админке школы («Школа» → «Кастомизация» → «Приложения и страницы», меню страницы «⋯» → «Показать секрет») и хранится только на вашем сервере. У каждой страницы свой секрет.
retrieveInitData, useExodeInitData и verifyInitData доступны в @exode-team/sdk начиная с версии 0.3.1.

В мини-приложении (браузер)

retrieveInitData читает fragment один раз, очищает его из адресной строки (чтобы подписанные данные не утекали при копировании ссылки) и кэширует значение. В React используйте хук useExodeInitData — он работает так же и не требует провайдера. Поля user и session_uuid есть только у авторизованного пользователя. Набор полей может расширяться — при проверке подписи учитывайте все поля, кроме hash.

На вашем сервере (Node.js)

При невалидной подписи, чужом секрете или протухшей auth_date функция бросает исключение (Error) — перехватите его и ответьте 401.

Формат подписи

Если вы не используете Node.js — проверить подпись можно вручную на любом языке:
Строка initData закодирована как application/x-www-form-urlencoded: при декодировании + означает пробел. Используйте стандартный парсер query-строк своего языка, а не ручной split. Секрет страницы используется как есть — это строка, декодировать её (hex/base64) не нужно. После проверки подписи сравните auth_date (unix-время в секундах) с текущим временем, чтобы отбросить устаревшие данные. Пример на Node.js без SDK:

Рекомендации по безопасности

  • Ограничьте окно auth_date (maxAgeSec) — 24 часа или меньше.
  • Отдавайте на страницах мини-приложения заголовок Content-Security-Policy: frame-ancestors https://<домен-вашей-школы> — это гарантирует, что приложение встроено именно в Exode.
  • Передавайте targetOrigin в конструктор ExodeMiniApp — origin страницы школы.
  • Никогда не проверяйте подпись в браузере: секрет не должен покидать ваш сервер.
  • При компрометации секрета перевыпустите его в админке (меню страницы «⋯» → «Перевыпустить секрет») — старые initData перестанут проходить проверку. Не забудьте обновить секрет на своём сервере.

Обновлено: 2026-09-25 13:43 UTC