Сессии клиента

Сессия отвечает на вопрос «когда и откуда клиент пользовался продуктом». Каждый успешный вход создаёт запись: какой клиент, в каком приложении, каким способом вошёл, с какого устройства, сколько времени провёл активно и чем всё закончилось.

Сессия заводится автоматически вместе с Bearer-токеном клиента — отдельного метода «начать сессию» нет. У одного токена в каждый момент не больше одной активной сессии, но за время его жизни их может смениться несколько: после долгого перерыва прежняя сессия закрывается, а следующий заход открывает новую с тем же токеном. Клиент, вошедший с телефона и с ноутбука, держит две параллельные сессии и может завершить их по отдельности.

Зачем это нужно продукту

• Поддержка видит контекст. Заходил ли клиент вообще, когда в последний раз и с какого устройства — это ответ за один запрос, а не догадки по заказам.
• Видно живую аудиторию. Признак «сейчас онлайн» и суммарное активное время показывают, пользуются продуктом или только зарегистрировались.
• Активное время считается честно. Учитывается не «вкладка открыта», а подтверждённая активность: клиент периодически шлёт heartbeat, и за один интервал засчитывается не больше 180 секунд, сколько бы вкладка ни висела.
• Выход работает предсказуемо. Клиент выходит на одном устройстве или сразу на всех: во втором случае удаляются все его токены, и остальные устройства перестают работать немедленно.
• Видно способ входа. По коду из звонка, письмом на email или из miniapp — у каждой сессии способ записан, и по нему видно, каким каналом входа люди реально пользуются.

Способы входа

Способ входа фиксируется в момент выдачи токена и дальше не меняется.

Как получить Bearer каждым из способов — на странице «Вход клиента».

Сколько живёт вход

Срок жизни зависит от способа входа, и это стоит учесть при проектировании клиента:

То есть продукт на входе звонком требует повторного входа примерно раз в сутки, а вход по коду держит клиента залогиненным долго. Точное время окончания в ответе на вход не приходит ни в одном из способов — узнать его можно через introspect, который отдаёт expires_at для любого токена.

Токен и сессия — не одно и то же. Токен решает, пустят ли запрос; сессия — это история пользования. Просроченный токен перестаёт работать сразу, а запись сессии остаётся в истории до плановой очистки.

Жизненный цикл сессии

1. Старт. Клиент вошёл — Gigma выдала токен и завела сессию с началом отсчёта, способом входа и названием устройства из поля device.
2. Активность. Клиент или ваш backend шлёт heartbeat примерно раз в минуту; каждый запрос двигает время последней активности и добавляет активное время.
3. Пауза. Если heartbeat не приходил 300 секунд, сессия закрывается задним числом — по времени последней активности, а не по моменту закрытия. Следующий heartbeat с тем же токеном откроет новую сессию с тем же способом входа: токен остаётся действующим, прервалась только запись о непрерывном пользовании.
4. Завершение. Сессия закрывается выходом клиента, простоем или перевыпуском токена.

Причина завершения хранится в поле end_reason:

Сессии хранятся 180 дней, затем удаляются. Вместе с удалением клиента удаляются и его сессии.

Как это видно в платформе

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

{
    "summary": {
        "last_login_at": "2026-08-18T09:12:00+00:00",
        "last_seen_at": "2026-08-18T10:04:00+00:00",
        "is_online": true,
        "total_duration_seconds": 5400
    },
    "sessions": [
        {
            "id": 128,
            "application": { "id": 275, "name": "Интернет-магазин" },
            "auth_method": "phone_code",
            "device": "iPhone, Safari",
            "status": "active",
            "started_at": "2026-08-18T09:12:00+00:00",
            "last_seen_at": "2026-08-18T10:04:00+00:00",
            "ended_at": null,
            "duration_seconds": 3120,
            "end_reason": null
        }
    ],
    "pagination": {
        "total": 42,
        "per_page": 20,
        "current_page": 1,
        "last_page": 3
    }
}

Что учесть при интеграции

• Сессия — это статистика, а не право доступа. Активная сессия ничего не говорит об оплате, а её отсутствие не означает, что клиент вышел: после простоя сессия закрыта, но Bearer продолжает работать. Правило проверки доступа — в интеграции с backend.
• Передавайте осмысленный device при входе — иначе в платформе сессия будет без устройства, и телефон не отличить от браузера.

Что почитать ещё

• Вход клиента — как получить Bearer каждым из способов.
• Heartbeat клиентской сессии — контракт учёта активности.
• Проверка Bearer через introspect — как серверу проверить токен клиента.