Ініціалізуйте віджет DobroDesk програмно

Виберіть програмне встановлення для сайту з кодом застосунку

Використовуйте programmatic SDK, якщо сайт є застосунком, а віджет має запускатися після згоди, входу, вибору маршруту або іншої події. Для конструктора сайтів або поля користувацького коду на весь сайт простіше використовувати стандартний script embed.

Обидва способи завантажують той самий віджет DobroDesk. SDK не створює окремої реалізації: він передає Integration ID і locale завантажувачу та надає типізовані методи керування віджетом.

• Використовуйте script embed, якщо кнопка "Підтримка" має завантажуватися на кожній публічній сторінці без логіки застосунку.
• Використовуйте SDK, якщо запуск залежить від стану застосунку або віджет має відкривати власна кнопка.
• Ініціалізуйте віджет один раз на сторінці. Зберігайте повернений client замість повторного виклику createDobroDeskWidget.
• Запускайте ініціалізацію в браузері. Під час серверного рендерингу немає document або window.

Установіть пакет

Додайте пакет віджета DobroDesk до frontend-застосунку через менеджер пакетів, який уже використовує проєкт.

npm install @dobrodesk/widget

Ініціалізуйте один екземпляр віджета

1. 1

   Скопіюйте Integration ID з Admin > Channels > Website widgets.

   

2. 2

   Імпортуйте createDobroDeskWidget у браузерному коді застосунку.

3. 3

   Передайте точний Integration ID у властивості integrationId і виберіть auto, en або uk.

4. 4

   Збережіть повернений client і дочекайтеся client.ready перед логікою, що залежить від успішного завантаження конфігурації.

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

const supportWidget = createDobroDeskWidget({
  integrationId: "wgt_7f4c1d2e3a5b6980718293a4b5c6d7e8",
  locale: "auto",
});

await supportWidget.ready;

Використайте розміщений ES module без менеджера пакетів

Браузерний застосунок із підтримкою ES modules може імпортувати той самий SDK напряму. Це підходить невеликому сайту з JavaScript modules, але без npm build step.

import { createDobroDeskWidget } from "https://dobrodesk.com/widget/sdk/v1.js";

const supportWidget = createDobroDeskWidget({
  integrationId: "wgt_7f4c1d2e3a5b6980718293a4b5c6d7e8",
  locale: "en",
  openOnReady: false,
});

Керуйте віджетом із дій застосунку

Зберігайте client у модулі або компоненті, який відповідає за підтримку. Якщо віджет відкриває власна кнопка Help або Support, ініціалізуйте його з launcher: hidden, щоб поруч не з'явилася стандартна кнопка. Після запуску логіка згоди може керувати видимістю кнопки, а prefill — передавати вже відомі дані клієнта.

• open, close і toggle змінюють стан панелі.
• hide прибирає віджет із взаємодії, а show знову робить його доступним.
• setLauncherVisibility приховує або показує лише стандартну кнопку, не знищуючи client віджета.
• prefill доповнює передані name, email, subject, message або налаштовані користувацькі поля.
• setLocale завантажує en або uk, а для іншої locale повертається до англійської.
• destroy остаточно видаляє екземпляр віджета з поточної сторінки.

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

await supportWidget.ready;

// Your application button
supportWidget.open();

// Consent or route state
supportWidget.setLauncherVisibility(false);
supportWidget.setLauncherVisibility(true);

supportWidget.close();
supportWidget.toggle();
supportWidget.hide();
supportWidget.show();

supportWidget.prefill({
  email: "customer@example.com",
  subject: "Question about order 1042",
});

supportWidget.setLocale("uk");

Безпечно ідентифікуйте авторизованих клієнтів через короткочасний JWT

Використовуйте підписану ідентичність клієнта, коли застосунок уже знає авторизованого користувача. DobroDesk перевіряє ID клієнта та, за потреби, підтверджений email перед прив'язуванням історії розмов або показом CRM-контексту. Identity secret має зберігатися лише в менеджері секретів backend.

У налаштуваннях віджета виберіть Require a signed logged-in user, збережіть віджет і натисніть Copy identity secret. Збережіть значення як DOBRODESK_WIDGET_IDENTITY_SECRET у backend. Публічний Integration ID можна передавати в браузер, identity secret — ні.

1. 1

   Установіть у backend підтримувану JWT-бібліотеку, наприклад jose.

2. 2

   Підписуйте HS256 з issuer dobrodesk-widget:{Integration ID}, audience, що дорівнює Integration ID, і subject, що дорівнює стабільному внутрішньому ID користувача.

3. 3

   Використовуйте строк дії п'ять хвилин і ніколи не більше 15 хвилин. Створюйте новий токен під час завантаження сторінки або входу користувача.

4. 4

   Додавайте email та email_verified: true лише після того, як застосунок підтвердив належність цієї адреси.

5. 5

   Поверніть токен з авторизованого backend endpoint і передайте його в identityToken під час створення віджета.

• sub — це стабільний ID користувача у вашому застосунку, а не email.
• email_verified: false або відсутнє значення не робить email довіреним.
• Якщо email є в identityToken або prefill.email, віджет не показує ще одне поле email.
• Непідписаний попередньо заповнений або введений email залишається непідтвердженим до переходу клієнта за одноразовим посиланням.
• Якщо вхід відбувся після ініціалізації, викличте setIdentityToken(token), а потім prefill({ email, name }).
• Перед виходом користувача з вашого застосунку викличте logout(), щоб інша людина в цьому браузері не отримала попередню розмову.

import { SignJWT } from "jose";

const integrationId = process.env.DOBRODESK_WIDGET_ID;
const identitySecret = new TextEncoder().encode(
  process.env.DOBRODESK_WIDGET_IDENTITY_SECRET,
);

export const createWidgetIdentityToken = (user) =>
  new SignJWT({
    name: user.name,
    email: user.email,
    email_verified: true,
  })
    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
    .setIssuer(`dobrodesk-widget:${integrationId}`)
    .setAudience(integrationId)
    .setSubject(user.id)
    .setIssuedAt()
    .setExpirationTime("5m")
    .sign(identitySecret);

// Browser code after your authenticated endpoint returns the token
const supportWidget = createDobroDeskWidget({
  integrationId,
  identityToken,
  prefill: { email: currentUser.email, name: currentUser.name },
});

Перевірте інтеграцію в застосунку

1. 1

   Відкрийте маршрут застосунку, який ініціалізує SDK, і переконайтеся, що відображається лише задумана стандартна або власна кнопка "Підтримка".

2. 2

   Запустіть власну дію, що викликає open, і перевірте відкриття панелі без перезавантаження сторінки.

3. 3

   Перевірте кожне попередньо заповнене поле на нечутливому тестовому значенні. Не передавайте у поля віджета платіжні дані, паролі або приватні токени.

4. 4

   Перемикайтеся між auto, en та uk і перевірте кнопку, поля форми та запропоновані відповіді.

5. 5

   Надішліть одне повне тестове повідомлення й перевірте, що воно надійшло до налаштованої папки DobroDesk Inbox.