Добавьте планирование маршрутов в вашу платформу

Обзор

Каждый уровень работает самостоятельно. Большинство партнёров начинают с уровня 1 (запуск одним кликом) и добавляют более высокие уровни позже, по мере изменения потребностей. В разделах ниже описывается опыт ваших конечных пользователей, что вы получаете как бизнес, полный разбор всех четырёх уровней и подробный анализ уровня 1. Раздел Технические детали далее содержит техническую спецификацию.

Что видят ваши пользователи

На уровне 1 Launch Pad работает как сопутствующее приложение к вашему продукту. Он открывается в новом окне браузера, при этом вся настройка выполняется в фоновом режиме, так что пользователь может сразу приступить к работе.

Что получаете вы как партнёр

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

Четыре уровня интеграции

Каждый уровень работает самостоятельно. Большинство партнёров начинают с уровня 1 и добавляют более высокие уровни позже, по мере изменения потребностей.

Как уровень 1 устраняет трения

Зачем нужен уровень 1

Модель аккаунта

Взаимодействие на уровне 1 организовано следующим образом:

Что пользователи видят в Launch Pad

Когда пользователь открывает Launch Pad через уровень 1, некоторые опции Launch Pad неприменимы и скрыты:

• Нет смены пароля, управления email или аккаунтом, нет регистрации. У пользователя нет пароля Launch Pad; вход осуществляется через ваш продукт. На экране смены пароля отображается сообщение «Пароль управляется [Партнёром]» — так же, как Launch Pad уже обрабатывает пользователей, входящих через John Deere, Trimble или CNH.
• Нет переключателя компании. Сессия привязана к единственной организации клиента на время визита.
• Выход заменён на «Вернуться к [Партнёру]», что закрывает вкладку или отправляет пользователя обратно на указанный вами URL, вместо того чтобы оставлять его на странице входа Launch Pad.

Главное рабочее меню (Планы, Планирование маршрутов, Оборудование, Сравнить) остаётся доступным, поскольку пользователям оно нужно для работы. Скрыты только опции удостоверения, расчётов, администрирования и управления аккаунтом.

Возврат плана маршрута

Когда пользователь заканчивает план маршрута в Launch Pad, результат нужно вернуть в ваш продукт. Доступны четыре варианта, и они работают поверх любого уровня. Push-варианты значительно предпочтительнее опроса (polling).

Сквозной поток

Что происходит шаг за шагом, когда пользователь партнёра открывает Launch Pad:

sequenceDiagram
    autonumber
    participant YU as UI партнёра
    participant YB as Бэкенд партнёра
    participant LA as Launch Pad API
    participant LU as Launch Pad UI

    YU->>YB: пользователь нажимает «Открыть план маршрута»

    note over YB,LA: Шаг 1: создать пользователя LP, если не существует
    YB->>LA: POST /api/users (idempotent on externalUserId)
    YB->>LA: POST /api/company-accesses (idempotent on user + org)

    note over YB,LA: Шаг 2 (опционально): передать границу поля
    YB->>LA: POST /api/vBoundary/upsert

    note over YB,LA: Шаг 3: запросить код запуска
    YB->>LA: POST /api/partner/launch ({ userId, companyId, returnUrl })
    LA-->>YB: { code, expiresInSec: 600 }

    YB-->>YU: 302 redirect to https://your-app.vergeag.com/launch?code=...
    YU->>LU: браузер переходит на /launch?code=...
    LU->>LA: POST /api/partner/launch/{code}/exchange
    LA-->>LU: JWT + refresh token
    note over LU: сохранить JWT в localStorage,
удалить код из URL,
перейти на returnUrl
          

Ключевые свойства

• Вы аутентифицируетесь сервер–сервер с долгосрочной учётной записью (API-ключ вашего администратора). Браузер никогда не видит API-ключ.
• Браузер видит только короткоживущий одноразовый непрозрачный код в URL (время жизни 10 минут, уничтожается при обмене).
• Эндпоинт обмена не требует входа; сам код является учётной записью. UI Launch Pad вызывает его, как только пользователь попадает на страницу.
• Launch Pad выдаёт обычную пользовательскую сессию (JWT + refresh token), сохраняет её в localStorage и перенаправляет пользователя на указанный вами URL.

Соответствие стандартам

Как выглядит URL переадресации

Что получает браузер пользователя (одна строка в виде заголовка Location:):

https://your-app.vergeag.com/launch?code=lc_R3w9q-Kx7VtNm2bH8sLpYj4eQ6gZc1aXfU0dT5nMoP&returnUrl=%2Fpath-planning%2Fboundary%2Fb3f47e1c-8a02-4d59-9c6e-2f7a8b1d6e09

В расшифрованном для чтения виде:

Что делает UI Launch Pad при переходе

Вы это не реализуете; информация приведена для справки, чтобы вы понимали, что происходит у ваших пользователей между кликом и отображением поля:

1. Читает code и returnUrl из строки запроса.
2. Обменивает код с Launch Pad на пользовательскую сессию.
3. Авторизует пользователя в нужной организации клиента.
4. Удаляет код из адресной строки, чтобы он не оставался в истории браузера.
5. Перенаправляет пользователя на указанный вами returnUrl.

Если code отсутствует, истёк или уже использован, пользователь попадает на страницу ошибки с просьбой вернуться в ваш продукт и попробовать снова.

Варианты возврата подробно

Более высокие уровни

Эта страница — полный справочник по уровню 1. Для более высоких уровней: