Додайте планування маршрутів до своєї платформи

Огляд

Кожен рівень працює самостійно. Більшість партнерів починають з рівня 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. Для вищих рівнів: