Навигация¶

BotFarm2 поддерживает навигацию пользователя по HTML-страницам вашего бекенда. Каждая кнопка (<a href="...">) — это переход на новую страницу. Система ведет стек навигации и поддерживает кнопку "Назад".

Как работает навигация¶

Пользователь нажимает кнопку с href="/catalog"
BotFarm2 запрашивает GET /catalog с вашего бекенда
HTML парсится, сообщение отправляется пользователю
Предыдущая страница добавляется в стек навигации

Кнопка "Назад" (.bf-back)¶

Кнопка с классом .bf-back возвращает пользователя на предыдущую страницу из стека.

<div class="bf-message">
    <span class="bf-text">Детали товара</span>
    <div class="bf-inline">
        <a href="/buy">Купить</a>
        <a href="#" class="bf-back">← Назад</a>
    </div>
</div>

Значение href у .bf-back игнорируется — BotFarm2 берет URL из стека навигации.

Стек навигации¶

По умолчанию все посещенные страницы попадают в стек. При нажатии "Назад" BotFarm2:

Находит последнюю запись в стеке
Запрашивает её URL
Удаляет из стека все записи до текущего base_url

Удаление дубликатов¶

Если пользователь посещает страницу, которая уже есть в стеке, все промежуточные записи удаляются:

Стек: Главная → Каталог → Товар → Каталог(повтор)
После удаления дубликата: Главная → Каталог

Метатеги навигации¶

Метатеги в <head> управляют поведением страницы в стеке.

bf-skip-stack¶

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

<head>
  <meta name="bf-skip-stack">
</head>

bf-stack¶

Работает в связке с настройкой бота stack_mode="only_stack". В этом режиме в стек попадают только страницы с этим метатегом.

<head>
  <meta name="bf-stack">
</head>

bf-strip-query¶

При наличии этого метатега base_url страницы вычисляется без query string (все GET-параметры убираются). Без него убирается только служебный параметр bf_page.

<head>
  <meta name="bf-strip-query">
</head>

Пример:

Страницы /profile?user_id=1 и /profile?user_id=2 — разные URL, но логически одна страница.

Без метатега: считаются разными страницами в стеке
С метатегом: base_url = /profile — считаются одной страницей, кнопка "Назад" пропустит обе

Навигация: Каталог → Профиль?user_id=1 → Профиль?user_id=2 → Товар

Без bf-strip-query:
  "Назад" на Товаре → Профиль?user_id=2
  "Назад" на Профиле?user_id=2 → Профиль?user_id=1
  "Назад" на Профиле?user_id=1 → Каталог

С bf-strip-query:
  "Назад" на Товаре → Профиль?user_id=2
  "Назад" на Профиле → Каталог (пропустил user_id=1 т.к. base_url совпадает)

Режимы стека¶

Настраивается на уровне бота (поле stack_mode):

Режим	Описание
`exclude_skip` (по умолчанию)	Все страницы попадают в стек, кроме тех, у которых есть `<meta name="bf-skip-stack">`
`only_stack`	В стек попадают только страницы с `<meta name="bf-stack">`

Пагинация кнопок¶

Если кнопок в .bf-inline больше, чем bot.page_size, они автоматически разбиваются на страницы.

<div class="bf-inline">
    <a href="/item1">Элемент 1</a>
    <a href="/item2">Элемент 2</a>
    <!-- ... 20 элементов ... -->
    <a href="/item20">Элемент 20</a>
</div>

Результат (страница 1):

[Элемент 1] ... [Элемент 15]
[    ←        →    ]

Размер страницы по платформам¶

Платформа	page_size по умолчанию
Telegram	16
Max	16
Instagram	30
VKontakte	5

Постоянные кнопки¶

Кнопки внутри .bf-inline-permanent отображаются на каждой странице пагинации:

<div class="bf-inline">
    <a href="/item1">Элемент 1</a>
    <!-- ... -->
    <div class="bf-inline-permanent">
        <a href="/">Главная</a>
        <a href="/cart">Корзина</a>
    </div>
</div>

URL-параметр пагинации¶

BotFarm2 добавляет ?bf_page=N к URL при навигации по страницам:

?bf_page=0  — первая страница
?bf_page=1  — вторая страница

Refresh — обновление сообщений¶

Механизм refresh_key позволяет обновлять ранее отправленные сообщения без повторной навигации.

Отправка с refresh_key¶

curl -X POST https://app2.botfarm.me/api/v1/navigate \
  -H "Authorization: Bearer TOKEN" \
  -d '{"url": "/scores", "user_ids": [1,2,3], "refresh_key": "scores_v1"}'

Обновление¶

curl -X POST https://app2.botfarm.me/api/v1/refresh \
  -H "Authorization: Bearer TOKEN" \
  -d '{"refresh_key": "scores_v1"}'

BotFarm2 находит все сообщения с этим ключом, перезапрашивает их URL у бекенда и:

Текстовые сообщения — редактируются на месте (edit)
Сообщения с фото — удаляются и отправляются заново

Максимум 10 000 сообщений за один вызов /refresh.

Навигация через API¶

При навигации через API (/api/v1/navigate) страница по умолчанию не попадает в стек навигации (эквивалент bf-skip-stack). Это поведение может быть переопределено метатегом на самой странице.