Хранилище JSONов от Telegram API

TL;DR

В качестве предисловия хочу обозначить пару моментов:

• данную статью можно считать полноценной продолжательницей предыдущей, в которой я рассматривал VK API — логика работы достаточно похожая
• для разработчиков, плотно работающих с мини-приложениями, боюсь, могу открыть секрет Полишинеля

Для всех остальных, надеюсь, данная статья раскроет некоторые малоиспользуемые методы работы с Telegram MiniApp. По крайней мере, мне при исследовании особо многого не попадалось.

Приятного чтения! 🤗

---

Трижды я принимался начинать статью, сделав по своему обыкновению философское вступление по теме, но всякий раз удалял, поскольку получалось совсем какое-то словоблудие вокруг темы. Поэтому, решил начать рассказ о том, как я нашёл ещё один способ хранить пользовательские данные для приложений (не прибегая к написанию своего API), с классики.

Смеркалось. И в сумраке угасающего дня решил я поковырять мини-приложения в Telegram. Уже детально не помню, что я там делал, но в какой-то момент решил посмотреть — а какие данные у нас есть в передаваемом от телеги объекте?

Здесь сделаю небольшое отступление — когда мы создаём мини-приложение Telegram, то по сути мы просто открываем веб-страницу по указанному в настройках адресу. Впридачу туда докидывается объект window.Telegram.WebApp, который содержит в себе много всего. Зачастую самое интересное, что там есть — это пользовательские данные. Оттуда мы можем получить его id, имя и прочую полезную информацию (например, текущую цветовую тему). И большинство различных статей, которые мне попадались, были посвящены конкретно работе с пользовательскими данными.

Но совершенно случайно — не иначе, как по воле провидения — я зацепился взглядом за очень интересный параметр, а именно CloudStorage. А мгновением позже я уже читал документацию…

В общем, CloudStorage в мини-приложениях Telegram — это некая аналогия localStorage браузера, только с одним маленьким нюансом: все вносимые изменения храняться не на отдельном устройстве, а в сети.

Да, там есть пара ограничений — каждый бот может хранить на одного пользователя не больше, чем 1024 элемента, а каждое значение ограничено всего лишь 4096 символами. С одной стороны, для графа де ла Фер это слишком мало, но для мушкетёра Атоса — в принципе, норм.

Всего у данного объекта несколько функций:

• setItem(key, value[, callback])
• getItem(key, callback)
• getItems(keys, callback)
• removeItem(key[, callback])
• removeItems(keys[, callback])
• getKeys(callback)

Думаю, пояснять тут что какая делает, смысла нет — они прям очевидные. Но и тут есть нюансик. Каждая из функций как минимум содержит callback-функцию, первый аргумент которой содержит ошибку, а второй — возвращаемое значение. Таким образом, если мы хотим получить какие-то данные, чтобы потом обработать, нам нужно написать примерно такой обработчик:

// Допустим, что нам нужно получить объект данных из ключа storage
WebApp.CloudStorage.getItem('storage', (error, result) => {

  // TODO: Тут честно себе пообещаем, что после релиза сделаем обработку ошибок

  // Парсим из строки нужный нам объект
  setData(JSON.parse(result))
})

А дальше уже используем по своему усмотрению.

Кроме этого, в объекте WebApp существует ещё пара очень полезных объектов — SecureStorage и DeviceStorage, которые тоже служат для хранения данных.

SecureStorage представляет собой специальный прокси-провайдер к защищённому хранилищу на устройстве, которое позволяет хранить чувствительные данные в зашифрованном виде. Разработчики рекомендуют использовать его для хранения токенов, секретов, состояния аутентификации и другой конфиденциальной пользовательской информации. Каждое приложение может хранить до 10 элементов на пользователя.

DeviceStorage ещё в большей степени, чем CloudStorage, похож на localStorage, даже хранится он только на конкретном устройстве. Зато может выделить до 5 мегабайт.

Практическое применение

Оговорюсь ещё раз — количество предоставляемого CloudStorage’ом свободного места не очень-то и много, поэтому на широкую ногу не разгуляешься. Однако, для каких-то не слишком глобальных задач его вполне себе можно использовать.

Кажется, самым простым способом попробовать данную технологию — это написать TODO. Но такую банальщину даже трогать не хочется, поэтому была рождена идея сделать Кальянный Дневник. Как появилась идея — это вообще отдельная история, но главное здесь в том, что в одном чате сошлись два человека:

1. тот, что идею вкинул (Антон, привет 👋 )
2. тот, что решил воплотить в реальность

А поскольку Антон ещё дизайны классные делает, то я его попросил нарисовать какой-нибудь прототип. И через непродолжительное время у меня появилась вот такая красота:

А дальше уже дело реализации. На проекте попытался я повайбкодить (использовал Lovable, Copilot и DeepSeek), но прям совсем чисто на промптах выехать не получилось. С одной стороны, часть функций они помогли написать быстро, но вот как был реализован экран с таймерами и количеством тяг… До последнего давал шанс ИИ как-то исправить ситуацию и не сбрасывать каждую минуту показатели тяжек в 0, но потом сдался и написал руками.

Результат вы можете попробовать сами — приложение уже доступно в Telegram для всех его пользователей на всех устройствах.

Итог

В целом, последние обновления API в Telegram прям сильно намекают, что у разработчиков планы на них большие. И данных, которыми располагают разработчики, стало очень и очень много.

Кроме объектов, которые позволяют нам хранить данные пользователей разными способами, в WebApp, я там нашёл прелюбопытнейшие объекты типа LocationManager, Accelerometer и Gyroscope. Для себя ещё узнал об HapticFeedback, который позволяет добавлять вибрации при нажатии на элементы интерфейса — вот как раз та штука, которая заставляла дрожать телефон, пока тапаешь хомяка.

Если говорить об облачном хранилище, то да — хоть какой-то полноценной заменой для API оно не станет, но в каких-то кейсах вполне себе можно использовать. Например, в том же приложении для кальяна — бесплатно хранить только последние х записей, а вот уже за звёздочки… Впрочем, это уже совсем другая история 😎.