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

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

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

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

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

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

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

npm install @dobrodesk/widget

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

1. 1

   Скопіюйте ID інтеграції з Налаштування > Канали > Віджети сайту.

   

2. 2

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

3. 3

   Передайте точний 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-модуль без менеджера пакетів

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

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

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

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

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

• open, close і toggle змінюють стан панелі.
• hide прибирає віджет із взаємодії, а show знову робить його доступним.
• setLauncherVisibility приховує або показує лише стандартну кнопку, не знищуючи клієнт віджета.
• prefill доповнює передані поля name, email, subject, message або налаштовані користувацькі поля.
• setLocale завантажує en або uk, а для іншої мови повертається до англійської.
• 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 клієнта та, за потреби, підтверджену електронну пошту перед прив'язуванням історії розмов або показом CRM-контексту. Секрет ідентифікації має зберігатися лише в менеджері секретів сервера.

У налаштуваннях віджета виберіть Вимагати підписаного автентифікованого користувача, збережіть віджет і натисніть Скопіювати секрет ідентифікації. Збережіть значення як DOBRODESK_WIDGET_IDENTITY_SECRET на сервері. Публічний ID інтеграції можна передавати в браузер, секрет ідентифікації — ні.

1. 1

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

2. 2

   Підписуйте HS256 з JWT-полем iss dobrodesk-widget:{ID інтеграції}, JWT-полем aud, що дорівнює ID інтеграції, і JWT-полем sub, що дорівнює стабільному внутрішньому ID користувача.

3. 3

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

4. 4

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

5. 5

   Поверніть токен з авторизованого серверного кінцевого пункту й передайте його в 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.