Односторінкові застосунки (React, Vue, Angular)

Встановіть скрипт як на будь-якому сайті. Віджет переживає зміну маршруту, бо сторінка не перезавантажується, і читає URL браузера щоразу, коли надсилається повідомлення, — тож зміну маршруту всередині додатка він помічає сам.

Варто додати три речі, кожна на кілька рядків.

Хай навігацію робить ваш роутер

Коли помічник відкриває сторінку, він надсилає на window подію shukai:action:navigate до того, як діє, і цю подію можна скасувати. Заберіть її собі й маршрутизуйте самі: повне перезавантаження сторінки в SPA гірше за ваш роутер.

window.addEventListener("shukai:action:navigate", (e) => {
  e.preventDefault(); // тепер наша — віджет не переходитиме сам
  router.push(new URL(e.detail.url).pathname);
});

Подія надсилається незалежно від того, чи ви її скасували, і маячок аналітики, що рахує перехід, теж спрацьовує в обох випадках, тож цифри власника «запропоновано → перейшли» не залежать від того, хто виконав навігацію. У Подіях перелічено всі події дій і що робить preventDefault() для кожної.

Коли URL не називає екран

Помічник знає, на якому екрані користувач, зіставляючи URL із шаблонами маршрутів, які власник вписав у джерело кожного екрана в панелі (/orders/{id} збігається з /orders/482 і дає {id: "482"}). Два випадки це ламають: хеш-маршрутизація (/#/orders/42 — pathname лише /) і один шлях для двох різних екранів. Тоді оголосіть маршрут самі:

router.afterEach((to) => {
  Shukai.setContext({ route: to.matched.at(-1).path, params: to.params });
});

Ваш додаток уже знає власний шаблон (Angular route.routeConfig.path, React Router path, Vue matched[].path). setContext — це стан, а не дія: його безпечно викликати до монтування віджета, він очікується на кожній зміні маршруту, а оголошений маршрут завжди перемагає зіставлений з URL. Обмеження: маршрут до 255 символів, до 20 параметрів, значення — рядки або числа.

Гортайте власний контейнер

«Гортай далі» рухає сторінку. Якщо body вашого додатка не гортається — оболонка з внутрішнім скролером, — віджет сам знаходить найбільший елемент, що гортається, або ви називаєте його атрибутом data-sa-scroll. Щоб узяти це повністю на себе, скасуйте shukai:action:scroll і гортайте свій контейнер:

window.addEventListener("shukai:action:scroll", (e) => {
  e.preventDefault();
  myScroller.scrollBy({ top: e.detail.direction === "down" ? 600 : -600 });
});

Дві речі, що не потребують коду

• Проактивна підказка (піднята рука) перевіряє URL раз на секунду, щоб помітити зміну маршруту, — вона не патчить history.pushState на вашій сторінці.
• Дії на сторінці читають екран заново, щойно це потрібно помічнику; автоматичний ідентифікатор живе лише доти, доки живе його елемент, тож дайте елементам data-sa-id — і ідентифікатори переживуть перемальовування (Розмітка елементів).

Користувачі, що увійшли

У додатку передайте віджету власний токен користувача після входу і очистіть його при виході, щоб помічник міг викликати ваш API від імені цього користувача: Ідентичність користувача.