Інтегруйте вебвіджет DobroDesk SDK

Установіть опублікований пакет

Браузерний пакет опубліковано за адресою https://www.npmjs.com/package/@dobrodesk/widget/v/0.3.1. Зафіксуйте версію пакета у lockfile та скопіюйте публічний Integration ID у Admin > Channels > Website widgets.

npm install @dobrodesk/widget@0.3.1

Налаштуйте й відкрийте віджет

Після встановлення скопіюйте публічний Integration ID у Admin > Channels > Website widgets і налаштуйте віджет у своєму застосунку.

Використовуйте launcher: hidden, якщо кнопкою керує ваш застосунок. Вбудований лаунчер ховається, поки панель відкрита, і повертає фокус після закриття. Не задавайте reduceMotion примусово, щоб віджет стежив за поточним системним налаштуванням відвідувача, включно зі змінами prefers-reduced-motion під час роботи.

import { createDobroDeskWidget } from "@dobrodesk/widget";

const widget = createDobroDeskWidget({
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  locale: "auto",
  launcher: "hidden",
});

await widget.ready;
widget.open();

Додайте власний тригер або вбудовану область

Залишайте launcher: hidden, коли кнопкою керує ваш продукт, і підключіть її до того самого клієнта віджета. Для вбудованої панелі заздалегідь задайте контейнеру сталу ширину та висоту, щоб компонування не стрибало під час завантаження.

Власна кнопка має бути доступною з клавіатури та мати aria-controls і aria-expanded. Не створюйте другий client під час повторного монтування маршруту. Повторно використовуйте наявний client, сесію та чернетку.

import { createDobroDeskWidget } from "@dobrodesk/widget";

const supportSlot = document.querySelector("#support-slot");
const helpButton = document.querySelector("#help-button");
if (!(supportSlot instanceof HTMLElement) || !(helpButton instanceof HTMLButtonElement)) {
  throw new Error("Support widget host elements are missing");
}

const widget = createDobroDeskWidget({
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  launcher: "hidden",
  container: supportSlot,
});

helpButton.addEventListener("click", () => widget.toggle());
widget.onStateChange((state) => {
  helpButton.setAttribute("aria-expanded", String(state.visible));
});
await widget.ready;

Опрацюйте завантаження та підписану ідентичність

Фрейм віджета показує індикатори завантаження для клієнта. Використовуйте onLoadingChange для стану сторінки, наприклад щоб вимкнути сусідню дію оформлення замовлення. Фази включають ініціалізацію, завантаження вмісту й сесії, доставку повідомлення, очікування помічника, виконання дії та повторне підключення.

Анонімні вебсесії підтримуються. Для підписаного клієнта ваш бекенд має видати короткоживучий identity JWT HS256, а браузер може передати його разом із відомою електронною адресою. Ніколи не розміщуйте signing secret або support API token у браузерному коді. Викликайте logout до завершення автентифікованої сесії хоста або перед передачею браузера іншому клієнту.

const stopLoading = widget.onLoadingChange((loading) => {
  checkoutButton.disabled = loading.active;
});

// The token is returned by your backend. This function belongs to your app.
widget.setIdentityToken(await loadIdentityTokenFromYourBackend());
widget.prefill({ email: currentUser.email, name: currentUser.name });

Керуйте завантаженням, видимістю та доступністю

Використовуйте onLoadingChange для стану сторінки, а індикатори завантаження повідомлень залишайте віджету. Поки надсилання очікує результату, не монтуйте другий елемент керування.

Для тимчасового переходу маршруту викликайте hide або show і зберігайте client та контейнер. Віджет враховує prefers-reduced-motion і його зміни. Прихований launcher та inline-панель усе одно мають доступний шлях закриття з клавіатури.

1. Під час тимчасового приховування викличте widget.hide() і збережіть client.
2. Після повторного монтування використайте той самий client і викличте widget.show().
3. Під час виходу з акаунта викличте widget.logout() і widget.destroy(), а потім створіть новий client.

Перевірте інтеграцію

1. Відкрийте сторінку з дозволеного origin і перевірте, що панель відкривається один раз, а прихований лаунчер залишається прихованим.
2. Надішліть тестове повідомлення з приватної сесії браузера, а потім перевірте, що воно потрапило до налаштованої Вхідної без створення другої розмови.
3. Ненадовго вимкніть мережу й дочекайтеся стану повторного підключення віджета. Дозвольте фрейму повторити власну незавершену дію. Не надсилайте те саме повідомлення з іншого елемента керування, поки перший запит не має результату.
4. Змініть системне налаштування reduced motion, коли віджет відкритий, і перевірте, що наступні переходи враховують нову перевагу.