События продукта

Чтобы воронка шла дальше визита — до регистрации, кредитов и оплат, — продукт присылает шаги пользователя в Webvane. CRM не нужна: продукт сам источник правды. Протокол — Journey Protocol v1.

Как это работает

1. Человек приходит в продукт по ссылке с меткой объявления (или из поиска). Счётчик Webvane запоминает его в cookie wv_vid на домене продукта.
2. При регистрации бэкенд продукта читает wv_vid и кладёт в событие signup вместе с номером аккаунта.
3. Webvane связывает аккаунт с визитами и меткой — канал, кампания, объявление, креатив известны.
4. Дальше продукт шлёт шаги только с номером аккаунта — асинхронно, через свою очередь.
5. Оплата пакета — payment, возврат — refund: отсюда выручка, LTV, CAC, ROMI.

Ключ и адрес

Маркетинг → Подключения, блок «Продукт: события пути пользователя» внизу страницы (туда же ведёт кнопка «Ключ событий продукта» в ответе мастера на «Подключить продукт»). Кнопки ключа видит только администратор.

• «Выпустить ключ» — ключ wvj_… показывается один раз, с кнопкой «Копировать»: сохраните его в настройках продукта. После обновления страницы виден только его начало: «Действует ключ wvj_…, выпущен …, последний приём …».
• «Перевыпустить ключ» — новый ключ, старый перестаёт работать сразу, без подтверждения.
• «Отозвать» — приём останавливается сразу, без подтверждения: «Ключа нет — продукт не может присылать события.»

Адрес приёма показан в блоке («Адрес приёма: …»), обычно https://ваш-сервер/api/journey/v1/events. Справа — «Что пришло за 30 дней»: таблица типов событий (сколько и когда последнее) за 30 дней; строка над ней — события, аккаунты и аккаунты, связанные с визитами, за всё время.

Формат запроса

POST /api/journey/v1/events
Authorization: Bearer wvj_…
Content-Type: application/json

{ "source": "pflux",
  "events": [ {
    "event_id": "bil-op-81233",
    "type": "credits_spent",
    "ts": "2026-10-17T09:15:02Z",
    "user": { "id": "4512", "vid": "ym:1712345678901234567" },
    "credits": { "amount": -3, "balance_after": 41 },
    "props": { "action": "send" } } ] }

Ответ 202: { "accepted": 1, "duplicates": 0, "rejected": [] }. До 500 событий и 1 МБ за раз. Повтор события с тем же event_id — дубль, а не двойной счёт: пачку можно слать повторно, пока не придёт 202.

События

Свои типы допустимы: строчная латиница, цифры, _ и ., первая — буква, до 64 символов.

Опознание пользователя

У события должен быть хотя бы один ключ: user.id (номер аккаунта), user.vid (cookie wv_vid) или user.email_sha256 (SHA-256 почты в нижнем регистре). Открытые почта и телефоны в props отклоняются. Запасной путь связи с визитом — вызов на странице продукта после входа: wv('identify', '4512') (Счётчик).

Асинхронная отправка

Отправлять событие прямо в запросе пользователя нельзя — Webvane может тормозить. Продукт пишет событие в свою таблицу- очередь в той же транзакции, что и само действие; фоновая задача раз в несколько секунд шлёт пачки. Ошибка сети, 5xx, 429 — повтор через 1, 5, 30 минут, 2 часа, 6 часов; отклонённое (rejected) не повторяется; 401 — ключ отозван.

Flux

Во Flux отправка уже есть — модуль webvane-journey: регистрации (с cookie wv_vid), начисления, списания, запросы, приглашения, оплаты. Включается переменными WEBVANE_JOURNEY_URL и WEBVANE_JOURNEY_KEY.

Ошибки

Ошибка всего запроса — код ответа и {"error": "…"}, пачка не принята, её можно отправить снова после исправления. Ошибка одного события — оно в rejected с причиной, остальные приняты; отклонённое не повторяйте.