Telegram Mini Apps: DeviceStorage и SecureStorage — локальное и защищённое хранилище

Мини-приложения Telegram (Mini Apps) получают два локальных хранилища: DeviceStorage подходит для кэша и состояния интерфейса, а SecureStorage — для небольших чувствительных значений. Оба объекта доступны через Telegram.WebApp; общую синхронизацию между устройствами следует строить через CloudStorage или собственный сервер.

Проверено 5 сентября 2026 года. Telegram добавил поля DeviceStorage и SecureStorage 11 апреля 2025 года в Bot API 9.0. На момент проверки официальная документация уже описывает Bot API 10.1 и по-прежнему содержит оба поля.

Содержание

1. Для кого это руководство
2. Как выбрать хранилище
3. Методы DeviceStorage
4. Методы SecureStorage
5. Подключение и проверка поддержки
6. Запись, чтение и восстановление
7. Полезные сценарии
8. Что делать, если хранилище не работает
9. Официальные источники

Для кого это руководство

Материал рассчитан на разработчиков Telegram Mini Apps, которые уже подключают клиентский JavaScript-комплект Telegram (SDK) и выбирают место для локальных настроек, кэша или чувствительных данных.

Руководство основано на официальной документации Telegram. Описанные операции в рамках этого редакторского прохода не запускались на реальном устройстве.

Как выбрать хранилище

DeviceStorage и SecureStorage не являются общим каналом синхронизации. SecureStorage поддерживает отдельный сценарий восстановления, но для общего состояния приложения используйте CloudStorage либо сервер.

DeviceStorage концептуально похож на браузерный localStorage, однако работает через асинхронные методы Telegram и колбэки. SecureStorage рассчитан на чувствительные значения, но не отменяет серверную проверку initData, ограничение срока и области действия учётных данных и возможность их отзыва.

Методы DeviceStorage

Операции вызываются через Telegram.WebApp.DeviceStorage. Результат передаётся через колбэк. Для записи, удаления и очистки второй аргумент сообщает об успехе.

Используйте префиксы вроде ui: и cache: для соглашения об именах и миграций. API не предоставляет выборочную очистку по префиксу: приложение должно само знать перечень принадлежащих подсистеме ключей и удалять их по одному.

Не считайте запись завершённой до вызова колбэка. Если setItem вернул ошибку, не обновляйте состояние приложения так, будто значение уже сохранено.

Методы SecureStorage

Операции доступны через Telegram.WebApp.SecureStorage.

Третий аргумент колбэка getItem — canRestore. Если значения нет, но canRestore равно true, приложение может предложить пользователю восстановление через restoreItem. Не запускайте восстановление автоматически: операция может потребовать взаимодействия с пользователем.

Подключение и проверка поддержки

1. Подключите официальный SDK

Загрузите https://telegram.org/js/telegram-web-app.js до остальных скриптов приложения. После загрузки SDK объект должен быть доступен как window.Telegram.WebApp.

2. Проверьте версию и наличие объекта

Сначала убедитесь, что существует window.Telegram.WebApp и что у него есть функция isVersionAtLeast. Затем вызовите tg.isVersionAtLeast('9.0'), где tg обозначает объект Telegram.WebApp.

Ветка работы с хранилищем считается доступной только при двух условиях: проверка версии вернула true, и нужное поле существует. Для DeviceStorage проверьте tg.DeviceStorage, для SecureStorage — tg.SecureStorage.

Одного номера версии недостаточно: наличие конкретного объекта защищает код от обращения к отсутствующему API в старом или несовместимом окружении. Эта проверка не заменяет проверку подлинности данных Mini App на сервере.

Если поддержка не подтверждена, предложите обновить Telegram или используйте заранее выбранный резервный канал. Для кросс-девайсных настроек подходит CloudStorage; обычное браузерное хранилище внутри WebView нельзя считать эквивалентом SecureStorage по модели защиты.

3. Подготовьте обработку асинхронного результата

Сначала проверяйте первый аргумент колбэка с ошибкой и только затем используйте значение или признак успеха. Ожидаемый результат успешной записи: ошибка отсутствует, а колбэк сообщает об успешной операции.

После успешной записи выполните контрольное чтение того же ключа. Проверка пройдена, если чтение вернуло ожидаемое значение без ошибки.

Запись, чтение и восстановление

Запись обычного значения

1. Получите Telegram.WebApp.DeviceStorage после проверки поддержки.
2. Вызовите setItem('ui:theme', 'dark', callback) со строковым ключом и значением.
3. Если колбэк вернул ошибку, оставьте рабочее состояние приложения без изменений.
4. После успешной записи вызовите getItem('ui:theme', callback).
5. Считайте проверку пройденной, если чтение вернуло dark без ошибки.

Для отсутствующего ключа обрабатывайте результат null как штатное состояние и применяйте значение по умолчанию.

Чтение чувствительного значения

1. После проверки поддержки получите Telegram.WebApp.SecureStorage.
2. Вызовите getItem(key, callback).
3. При ошибке перейдите к безопасному резервному сценарию и не раскрывайте значение или технические подробности в пользовательском сообщении.
4. Если значение получено, передайте его только компоненту, которому оно необходимо. Не выводите его в консоль и аналитику.
5. Если значения нет и canRestore равно false, запросите повторную авторизацию или создайте новое значение.

Восстановление защищённого элемента

1. Предлагайте восстановление только после результата getItem, в котором canRestore равно true.
2. Объясните пользователю, зачем потребуется системное подтверждение.
3. После согласия вызовите restoreItem(key, callback).
4. При успехе используйте возвращённое значение без журналирования его содержимого.
5. При отмене или ошибке оставьте доступным обычный сценарий повторной авторизации.

Проверяемый результат: приложение либо получает восстановленное значение, либо корректно переходит к повторной авторизации, не зависая и не считая отмену успешным восстановлением.

Полезные сценарии

Быстрый старт интерфейса из локального состояния

Задача. Сохранить тему, язык, последний открытый раздел и другие некритичные настройки.

Действие. Запишите настройки в DeviceStorage, а при следующем запуске прочитайте их до загрузки необязательных данных с сервера.

Проверяемый результат. После перезапуска Mini App на том же устройстве сохранённая настройка восстанавливается.

Ограничение. На другом устройстве локальное значение может отсутствовать; общее состояние храните в CloudStorage или на сервере.

Офлайн-кэш с последующим обновлением

Задача. Быстро показать ранее загруженные списки, справочные данные или контент, пока сеть запрашивает свежую версию.

Действие. Положите кэш в DeviceStorage, сохраните рядом версию формата или время обновления, покажите совместимую запись и параллельно запросите актуальные данные.

Проверяемый результат. При старте отображается допустимый кэш, а после ответа сервера интерфейс обновляется свежими данными.

Ограничение. Этот сценарий не подходит для данных, которые должны быть одинаковыми на всех устройствах или всегда отражать актуальное состояние операции.

Разделение данных при миграции с CloudStorage

Разложите существующие ключи по назначению:

• локальные настройки и воспроизводимый кэш перенесите в DeviceStorage;
• данные, нужные на разных устройствах, оставьте в CloudStorage или на сервере;
• небольшие чувствительные значения храните в SecureStorage;
• серверные источники истины не заменяйте локальной копией.

После миграции проверьте запуск на прежнем и новом устройстве, отсутствие значения, очистку хранилища и переход на резервный сценарий.

Стабильное локальное назначение варианта интерфейса

Задача. Закрепить вариант интерфейса на одном устройстве, чтобы пользователь не переходил между группами при каждом запуске.

Действие. Сохраните идентификатор варианта в DeviceStorage и используйте его при следующем запуске.

Проверяемый результат. На одном устройстве вариант остаётся тем же после перезапуска Mini App.

Ограничение. Если эксперимент должен закрепляться за пользователем на всех устройствах, назначение храните на сервере или в синхронизируемом хранилище.

Что делать, если хранилище не работает

• Нет Telegram.WebApp. Проверьте загрузку официального SDK и запуск страницы внутри Telegram.
• Нет DeviceStorage или SecureStorage. Проверьте наличие isVersionAtLeast, результат isVersionAtLeast('9.0') и самого поля; при необходимости предложите обновить клиент.
• Колбэк вернул ошибку. Не считайте операцию успешной, не затирайте рабочее состояние и предложите повторить действие.
• После записи чтение пустое. Проверьте совпадение ключа, дождитесь колбэка записи и повторите контрольное чтение.
• Данные есть на одном устройстве, но отсутствуют на другом. Для локальных хранилищ это ожидаемое ограничение; используйте CloudStorage или серверную синхронизацию. Для SecureStorage отдельно проверьте canRestore.
• SecureStorage.getItem не вернул значение. При canRestore: true предложите восстановление, при false переходите к повторной авторизации.
• Пользователь отменил восстановление. Не запускайте бесконечный повтор и оставьте обычный способ входа.
• Достигнут лимит. Для DeviceStorage удалите ненужный кэш или уменьшите объём данных; для SecureStorage сократите число элементов и не используйте его для крупного состояния.
• Нужно удалить часть данных. Используйте removeItem для известных ключей. clear удаляет всё хранилище соответствующего типа для текущего приложения на устройстве, поэтому перед вызовом проверьте область удаления.

Официальные источники

• Telegram Mini Apps: техническая документация
• DeviceStorage
• SecureStorage
• CloudStorage
• Изменения Bot API от 11 апреля 2025 года

Следующий шаг

Если хранилище — только часть Mini App, следующим шагом полезно сверить остальные возможности бота в справочнике «Возможности Telegram-ботов — справочник по Bot Features».

Связанные материалы

• Люди + агенты в одном чате: как мы собрали рабочий контур в Telegram
• Redis — хранилище данных в памяти
• Варианты управляемого S3-хранилища в России

При выборе хранилища полезно сопоставить требования к синхронизации, объёму и защите данных с архитектурой всего приложения. Обсуждение особенно пригодится команде, которая проектирует Mini App и серверную часть одновременно.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov