Лаунчер для Telegram

Этот документ призван рассказать о том, как работает лаунчер Платформера для мессенджера Telegram, каковы его особенности и требования.

Исходный код лаунчера доступен по этой ссылке.

Требования

Для корректной работы лаунчера, Ваше мини-приложение должно использовать одну из библиотек:

• @tma.js/sdk
• @tma.js/bridge

Отсутствие поддержки Telegram SDK

Лаунчер не работает с мини-приложениями, базирующимися на Telegram SDK, так как тот содержит ошибку, не позволяющую ланучеру корректно коммуницировать с Вашим мини-приложением.

В случае, если Вы используете @tma.js/sdk или @tma.js/bridge, не забудьте указать корректный target origin. Это позволит библиотеке корректно коммуницировать с лаунчером Платформера:

import { setTargetOrigin } from '@tma.js/sdk'; // или '@tma.js/bridge'

setTargetOrigin('https://tgl.mini-apps.store');

Доступные опции

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

Name	Type	Description
app_id	number	Идентификатор Вашего приложения в Платформере, который можно получить в панели управления.
fallback_url	string	Опционально. Ссылка, которую нужно использовать в случае, если Платформер оказался недоступным. При помощи этого параметра можно быть уверенным, что Ваше приложение откроется даже в случае, если с Платформером что-то не так.
init_timeout	number	Опционально. Время в миллисекундах для загрузки данных от сервера Платформера. Если это время истекло, лаунчер использует опцию fallback_url, чтобы отобразить приложение. Если fallback_url не указан, лаунчер покажет страницу с ошибкой. Значение по умолчанию - 5000 (5 секунд).
load_timeout	number	Опционально. Время в миллисекундах для загрузки Вашего приложения. Если это время истекло, лаунчер покажет ошибку. Значение по умолчанию - 10000 (10 секунд).

Отладка

Лаунчер позволяет включать отладочные функции с помощью start-параметра Telegram Mini Apps.

Название	Описание
p-debug	Включает режим отладки, выводя полезные логи в консоль.
p-eruda	Отображает консоль eruda. Обратите внимание, что при её включении сначала будет загружена сама eruda, а затем всё приложение. Используйте только для разработки или отладки.

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

Вот пример корректной ссылки, включающей все функции:

https://t.me/bot/app?start=p-debug_p-eruda
// или
https://t.me/bot?startapp=p-debug_p-eruda

Использование

Чтобы начать использовать лаунчер, возьмите его базовый URL (https://tgl.mini-apps.store/) и добавьте к нему следующие параметры в виде списка query-параметров.

Например, если у вас есть приложение в Платформере с идентификатором 10 и задан fallback_url, равный https://walletbot.me/app, итоговая ссылка будет выглядеть так:

https://tgl.mini-apps.store/?app_id=10&fallback_url=https%3A%2F%2Fwalletbot.me%2Fapp

Как только у вас будет конечный URL, используйте его при создании мини-приложения в @BotFather. При открытии вашего приложения клиент Telegram загрузит указанный выше URL, а уже по нему и Ваше приложение.

Используйте генератор ссылки

Чтобы упростить процесс создания такой ссылки, в панели управления Платформера перейдите к информации о приложении, и далее в раздел "Telegram -> Настройки лаунчера". Он поможет вам сгенерировать необходимую ссылку.

Принцип работы

Шаг 1. Чтение и проверка опций

Лаунчер считывает и проверяет переданные опции, чтобы убедиться, что они корректны. Если что-то указано неверно, будет показана страница с ошибкой.

Шаг 2. Аутентификация пользователя

Лаунчер извлекает токен авторизации Платформера для взаимодействия с его API. Если токен отсутствует, проводится процедура аутентификации и токен сохраняется локально.

Шаг 3. Получение данных приложения

Лаунчер получает информацию о приложении на основе опции app_id.

После получения данных отображается один из следующих экранов:

1. Сообщение о недоступности приложения по какой-либо причине — это может быть ошибка, отсутствие URL для текущей платформы или настройки безопасности приложения.
2. Само приложение, если от сервера Платформера был возвращён URL.

Шаг 4. Отображение приложения

Лаунчер вставляет iframe с URL, полученным от Платформера. Этот URL соответствует указанному в админ-панели, с учётом параметров запуска, переданных мини-приложению.

После вставки iframe лаунчер ждёт количество миллисекунд, указанное в опции load_timeout, до тех пор, пока ваше приложение не вызовет метод web_app_ready.

Чтобы избежать неконтролируемого поведения, В отличие от Telegram, Платформер не отображает приложение автоматически после загрузки всех ресурсов. Поэтому вызов метода web_app_ready обязателен.

Вопросы безопасности

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

Самая чувствительная часть данных — это init data, передаваемая Telegram при запуске мини-приложения. Чтобы исключить любые риски злоупотребления (например, подделку пользователя в чужом приложении), лаунчер автоматически удаляет параметр hash из init data, тем самым делая невозможным его повторное использование.

Вместо этого используется недавно представленная функция Telegram — Third-Party Validation. Она позволяет верифицировать подлинность init data с помощью свойства signature. Благодаря этому Платформер требует от Вас лишь одно: указать ID вашего Telegram-бота в админ-панели мини-приложения.

Устранение неполадок

Приложение не загрузилось из-за тайм-аута

Ваше приложение может не отобразиться по одной из следующих причин:

• Низкая скорость загрузки — Ваш сервер слишком долго загружал ресурсы приложения.
• Не вызван обязательный метод — Ваше приложение не вызвало метод web_app_ready.
• Несовместимая версия SDK — Платформер не поддерживает Telegram SDK или @telegram-apps/sdk из-за некорректной реализации связи между мини-приложениями и клиентом Telegram. Использование @tma.js/sdk или @tma.js/bridge должно решить эту проблему.
• Не установлен target origin — лаунчер Платформера не получает вызов метода web_app_ready, так как корректное значение targetOrigin не было установлено.