Как правильно работать с Back Button и навигацией в Telegram Mini App

Вы открыли Telegram Mini App, нажали кнопку назад - и вдруг приложение закрылось полностью. Или перекинуло на другую вкладку, которую вы не ожидали. Или вообще зависло. Это не баг - это навигация, которую большинство разработчиков делают неправильно.

В Telegram Mini App кнопка назад (Back Button) - это не просто кнопка. Это главный элемент управления, который пользователь ждёт, как в обычном браузере. Но если вы не настроите её правильно, пользователь уйдёт. По данным Telegram, 68% пользователей покидают Mini App, если навигация кажется непредсказуемой. Это не про стиль. Это про доверие.

Как работает Back Button в Telegram Mini App

В Telegram Mini App кнопка назад - это не системная кнопка телефона. Это кнопка в шапке самого приложения. Она появляется автоматически, когда вы используете Telegram.WebApp.BackButton. Но она не делает ничего сама по себе. Вы должны сказать ей, что делать.

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

Вот как это работает на практике: когда пользователь переходит со страницы A на страницу B, вы должны явно добавить это состояние в историю навигации. Иначе Telegram не знает, что на странице A было что-то важное. Он видит только текущий экран. И если вы не скажете ему обратное - он закроет всё.

Как правильно настроить навигацию

Чтобы Back Button работал как ожидается, нужно три вещи:

1. Включить кнопку назад явно
2. Отслеживать состояние страниц
3. Обрабатывать событие нажатия

Вот простой пример на JavaScript:

// Включаем кнопку назад
Telegram.WebApp.BackButton.show();

// Обрабатываем нажатие
Telegram.WebApp.BackButton.onClick(() => {
  if (currentScreen === 'product-detail') {
    // Возвращаемся на список
    showScreen('product-list');
  } else if (currentScreen === 'checkout') {
    // Возвращаемся к корзине
    showScreen('cart');
  } else {
    // Если мы на главной - закрываем приложение
    Telegram.WebApp.close();
  }
});

Это не сложнее, чем обрабатывать клик на кнопке. Но многие разработчики пропускают этот шаг. Они думают: «Telegram сам разберётся». Нет. Он не разберётся. Он ждёт от вас инструкций.

Что происходит, если вы не управляете навигацией

Представьте, что пользователь:

• Открыл приложение - попал на главную
• Перешёл в каталог товаров
• Выбрал один товар - попал на страницу деталей
• Нажал «Добавить в корзину» - открылась модалка
• Закрыл модалку - вернулся на страницу товара
• Нажал «Назад» - и приложение закрылось

Почему? Потому что вы не добавили состояние модалки в историю. Telegram видит только: главная → каталог → товар → [ничего]. Он не знает, что модалка была открыта. Он думает: «Пользователь на последнем экране. Назад - значит закрыть».

Это распространённая ошибка. Особенно когда используются фреймворки вроде React или Vue. Компоненты рендерятся, но история навигации не обновляется. Вы используете useState, но не вызываете Telegram.WebApp.BackButton.show() при каждом переходе.

Как управлять состоянием навигации

Создайте простой стек - как в нативных приложениях. Каждый раз, когда пользователь переходит на новый экран, добавляйте его в массив. Когда нажимаете «Назад» - удаляйте последний элемент и отображайте предыдущий.

const navigationStack = [];

function navigateTo(screen, data = null) {
  navigationStack.push({ screen, data });
  Telegram.WebApp.BackButton.show();
  renderScreen(screen, data);
}

function goBack() {
  if (navigationStack.length <= 1) {
    Telegram.WebApp.close();
    return;
  }
  navigationStack.pop();
  const previous = navigationStack[navigationStack.length - 1];
  renderScreen(previous.screen, previous.data);
}

// Используем
navigateTo('home');
navigateTo('catalog');
navigateTo('product', { id: 123 });

Telegram.WebApp.BackButton.onClick(goBack);

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

Особенности: модалки, всплывающие окна и вкладки

Модалки - это не отдельные экраны. Они не должны добавляться в стек. Если вы открыли модалку «Подтверждение удаления» - вы не переходите на новый экран. Вы просто поверх текущего. Значит, кнопка назад должна закрыть модалку, а не вернуться на предыдущий экран.

Вот как это сделать:

let modalOpen = false;

function openModal() {
  modalOpen = true;
  // показываем модалку
  Telegram.WebApp.BackButton.hide(); // прячем кнопку назад
}

function closeModal() {
  modalOpen = false;
  // скрываем модалку
  Telegram.WebApp.BackButton.show(); // снова показываем
}

Telegram.WebApp.BackButton.onClick(() => {
  if (modalOpen) {
    closeModal();
  } else {
    goBack();
  }
});

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

А вот вкладки (tabs) - это другое. Если пользователь переключается между вкладками «Каталог», «Корзина», «Профиль» - это полноценные экраны. Каждая вкладка должна быть в стеке. Иначе, если он перешёл с «Корзины» на «Профиль», а потом нажал назад - он должен вернуться в «Корзину», а не закрыть приложение.

Проверка: как понять, что навигация работает правильно

Проведите простой тест. Откройте приложение. Сделайте 5 переходов. Нажмите назад 5 раз. Что должно произойти?

• Каждое нажатие должно возвращать на предыдущий экран
• После пятого нажатия - приложение должно закрыться
• Никаких зависаний, перезагрузок, пропусков экранов
• Модалки закрываются, а не меняют экран

Если что-то не так - ищите место, где вы не вызвали show() или не добавили экран в стек. Часто ошибка в том, что вы вызываете show() только при старте, а не при каждом переходе.

Что ещё важно: состояние и данные

Когда вы возвращаетесь на экран, данные должны остаться. Если пользователь прокрутил список товаров до 15-го элемента - он не хочет, чтобы при возврате он снова оказался в начале. То же с формами: если он начал заполнять адрес, но нажал назад - он не хочет терять введённое.

Используйте локальное хранилище: localStorage или sessionStorage. Или сохраняйте состояние в памяти приложения. Просто не перезагружайте данные при каждом рендере.

Пример: если пользователь искал «наушники» в каталоге, а потом перешёл в корзину и вернулся - фильтр и результаты поиска должны остаться. Иначе вы заставляете его искать заново. Это раздражает. И пользователь уходит.

Частые ошибки и как их избежать

• Ошибка 1: Не вызываете Telegram.WebApp.BackButton.show() после перехода. → Решение: вызывайте её каждый раз, когда меняется экран.
• Ошибка 2: Используете window.history как в браузере. → Решение: Telegram не использует браузерную историю. Управляйте своей.
• Ошибка 3: Скрываете кнопку назад, но не показываете обратно. → Решение: всегда вызывайте show() после закрытия модалки или попапа.
• Ошибка 4: Закрываете приложение при первом нажатии назад. → Решение: пусть пользователь хотя бы один раз вернётся, прежде чем закрыть.
• Ошибка 5: Не проверяете длину стека перед close(). → Решение: всегда проверяйте, есть ли ещё экраны в стеке.

Что делать, если пользователь нажал назад слишком быстро

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

Добавьте простую защиту:

let isProcessingBack = false;

Telegram.WebApp.BackButton.onClick(() => {
  if (isProcessingBack) return;
  isProcessingBack = true;

  if (modalOpen) {
    closeModal();
  } else if (navigationStack.length > 1) {
    navigationStack.pop();
    renderScreen(navigationStack[navigationStack.length - 1].screen);
  } else {
    Telegram.WebApp.close();
  }

  // Сбрасываем флаг через 300 мс
  setTimeout(() => isProcessingBack = false, 300);
});

Это предотвращает двойные срабатывания и дает время на анимацию перехода.

Заключение: навигация - это не опция, а основа

В Telegram Mini App навигация - это то, что делает приложение ощущаемым. Если пользователь чувствует, что он «потерялся» - он уходит. Нет никакого смысла в красивом дизайне, если он не может вернуться назад.

Вы не создаёте веб-сайт. Вы создаёте приложение, которое живёт внутри Telegram. И в приложениях пользователь ожидает предсказуемости. Кнопка назад - это его якорь. Не ломайте его.

Простое правило: каждый экран - это шаг. Каждый шаг - в стек. Каждое нажатие назад - возвращает на предыдущий шаг. И только когда шагов больше нет - закрывайте приложение.

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