Перейти к содержанию

Документация WikilectWidget API

Для разработчиков

Этот раздел предназначен для разработчиков, которые хотят расширить функциональность виджета Wikilect или интегрировать его с собственными системами. Здесь описаны все доступные методы API, события и примеры их использования.

Оглавление

Введение

WikilectWidget API предоставляет интерфейс для взаимодействия с виджетом Wikilect. API реализован как синглтон, доступный через глобальный объект window.WikilectWidget.

Инициализация

API автоматически инициализируется при загрузке скрипта. Отдельная инициализация не требуется.

window.WikilectWidget;

Уведомление о готовности скрипта

Для получения уведомления о том, что скрипт виджета загружен и API готов к использованию, необходимо подписаться на DOM событие wikilect-script-ready.

Важно: Событие wikilect-script-ready срабатывает когда API создан, но виджет еще не вставлен в DOM. Для вызова методов API (например, ChatOpen()) необходимо дождаться события onWidgetReady.

Правильная последовательность событий

<script>
  // 1. Слушаем готовность скрипта (API создан)
  window.addEventListener("wikilect-script-ready", (event) => {
    console.log("Скрипт загружен, API готов:", event.detail.api);

    // 2. Подписываемся на готовность виджета (виджет отрендерен)
    window.WikilectWidget.on("onWidgetReady", () => {
      console.log("Виджет готов к взаимодействию");

      // 3. Теперь можно безопасно вызывать методы API
      window.WikilectWidget.ChatOpen();
    });
  });
</script>

<!-- Wikilect widget START -->
<script type="text/javascript" async>
  ....
</script>
<!-- Wikilect widget END -->

Уровни готовности

  1. wikilect-script-ready - скрипт загружен, API создан, можно подписываться на события
  2. onWidgetReady - виджет отрендерен, можно вызывать методы API
  3. Методы API - безопасно вызывать только после onWidgetReady

Что можно делать в wikilect-script-ready

✅ Можно:

❌ Нельзя (требуют готовности виджета в DOM):

Методы API

Управление пропсами

GetProps(): sharedPropsType

Возвращает текущие пропсы виджета (raw).

const currentProps = window.WikilectWidget.GetProps();

Управление чатом

ChatOpen()

Открывает чат, регистрирует пользователя в виджете, закрывает список опций(телефон/тг/чат).

window.WikilectWidget.ChatOpen();

ChatClose()

Закрывает чат и закрывает список опций(телефон/тг/чат).

window.WikilectWidget.ChatClose();

ChatReconnect()

Переподключение к WebSocket чата.

window.WikilectWidget.ChatReconnect();

Управление опциями

OptionsOpen()

Открывает список опций (телеграм/телефон/чат) и вызывает регистрацию пользователя.

window.WikilectWidget.OptionsOpen();

OptionsClose()

Закрывает список опций с тг/телефон/чат.

window.WikilectWidget.OptionsClose();

Управление сообщениями

UserSendMessage(message: string)

Отправляет сообщение в чат.

window.WikilectWidget.UserSendMessage("Привет!");

Управление пользователем

UserRegistration(force?: boolean)

Регистрирует пользователя в виджете. При force=true перерегистрирует даже если уже зарегистрирован.

Регистрация пользователя если таковой нет.

window.WikilectWidget.UserRegistration();

Принудительная регистрация, cбрасывает текущую регистрацию.

window.WikilectWidget.UserRegistration(true);

UpdateUserUtm(utmParams: Record<string, unknown>)

Обновляет/добавляет UTM-метки для текущего пользователя(если в localStorage есть запись wikilect-user-${widget_id}).

window.WikilectWidget.UpdateUserUtm({
  utm_source: "google",
  utm_medium: "cpc",
});

UpdateUserInfo(extraInfo: Record<string, unknown> | string)

Обновляет/добавляет информацию для текущего пользователя(если в localStorage есть запись wikilect-user-${widget_id}) в формате js объекта или JSON строки.

JS объект

window.WikilectWidget.UpdateUserInfo({
  price: "2000",
});

JSON строка

window.WikilectWidget.UpdateUserInfo('{"price":"0"}');

UserLogOut()

Разлогинивает пользователя из виджета.

window.WikilectWidget.UserLogOut();

Дополнительные функции

Открывает ссылку на Telegram(вместе с utm-метками) и вызывает регистрацию пользователя.

window.WikilectWidget.OpenTelegramLink();

OpenPhoneNumber()

Открывает номер телефона и вызывает регистрацию пользователя.

window.WikilectWidget.OpenPhoneNumber();

RemoveUtm()

Удаляет UTM-метки.

window.WikilectWidget.RemoveUtm();

SetWelcomeText()

Показывает приветственный текст и закрывает список опций(телефон/тг/чат).

window.WikilectWidget.SetWelcomeText();

Хранение данных

API использует localStorage для хранения следующих данных:

  • wikilect-jwt-${widget_id}: JWT токен пользователя
  • wikilect-utm-${widget_id}: UTM метки
  • wikilect-user-${widget_id}: ID пользователя, максимальная длина 20
  • wikilect-welcome-${widget_id}: Статус приветственного сообщения

События

API использует внутреннюю систему событий для коммуникации между компонентами. Основные типы событий:

  • ChatOpen
  • ChatClose
  • OptionsOpen
  • OptionsClose
  • UserSendMessage
  • ChatReconnect
  • OpenTelegramLink
  • OpenPhoneNumber
  • UserRegistration
  • SetWelcomeText

Колбеки

API предоставляет систему колбеков для отслеживания различных событий виджета.

Управление колбеками

Коллбек - on

Добавляет колбек для определенного события. on(event: string, callback: (data?: unknown) => void)

window.WikilectWidget.on("onWidgetOpen", () => {
  console.log("Виджет открыт");
});

Колллбек - off

Удаляет ранее добавленный колбек. off(event: string, callback: (data?: unknown) => void)

const callback = () => console.log("Виджет открыт");
window.WikilectWidget.on("onWidgetOpen", callback);
// ... позже
window.WikilectWidget.off("onWidgetOpen", callback);

Доступные события для колбеков

onWidgetReady

Вызывается когда виджет полностью отрендерен и готов к взаимодействию с пользователем (после завершения анимаций инициализации).

window.WikilectWidget.on("onWidgetReady", () => {
  console.log("Виджет готов к использованию");
});

Критически важно: Все методы API можно вызывать только после события onWidgetReady. Вызов методов до этого события приведет к ошибкам.

// ✅ Правильно - вызов после onWidgetReady
window.WikilectWidget.on("onWidgetReady", () => {
  window.WikilectWidget.ChatOpen();
});

// ❌ Неправильно - вызов до onWidgetReady
window.WikilectWidget.ChatOpen(); // Ошибка!

Последовательность событий:

  1. wikilect-script-ready - API создан, можно подписываться на события
  2. onWidgetReady - виджет готов, можно вызывать методы API
  3. Методы API - безопасно вызывать только после onWidgetReady

onWidgetOpen

Вызывается при открытии виджета со списком опций (телеграм/телефон/чат).

window.WikilectWidget.on("onWidgetOpen", () => {
  console.log("Пользователь открыл список опций/кликнул по виджету");
});

onWidgetClose

Вызывается при закрытии виджета со списком опций (телеграм/телефон/чат).

window.WikilectWidget.on("onWidgetClose", () => {
  console.log("Пользователь закрыл список опций/кликнул по виджету");
});

onBotMessageReceived

Вызывается при получении сообщения от бота в чате.

window.WikilectWidget.on("onBotMessageReceived", (message) => {
  console.log("Получено сообщение от бота:", message);
});

onManagerMessageReceived

Вызывается при получении сообщения от менеджера в чате.

window.WikilectWidget.on("onManagerMessageReceived", (message) => {
  console.log("Получено сообщение от менеджера:", message);
});

onError

Вызывается при возникновении ошибок в чате.

window.WikilectWidget.on("onError", (error) => {
  console.log("Произошла ошибка:", error);
});

onTelegramClick

Вызывается при клике на ссылку Telegram.

window.WikilectWidget.on("onTelegramClick", () => {
  console.log("Пользователь кликнул по кнопке телеграм");
});

onPhoneClick

Вызывается при клике на номер телефона.

window.WikilectWidget.on("onPhoneClick", () => {
  console.log("Пользователь кликнул по кнопке телефона");
});

onUserRegistered

Вызывается при регистрации пользователя в виджете.

window.WikilectWidget.on("onUserRegistered", (userData) => {
  console.log("Пользователь зарегистрирован:", userData);
});

onChatStatus

Вызывается когда чат виджета или открытый чат подключен к websocket и проведена авторизация.

window.WikilectWidget.on("onChatStatus", (status: boolean) => {
  console.log("Статус чата:", status);
});

onChatOpen

Вызывается при открытии чата.

window.WikilectWidget.on("onChatOpen", () => {
  console.log("Пользователь открыл чат");
});

onChatClose

Вызывается при закрытии чата.

window.WikilectWidget.on("onChatClose", () => {
  console.log("Пользователь закрыл чат");
});

onUserSentMessage

Вызывается когда сообщение пользователя отправлено в чат.

window.WikilectWidget.on("onUserSentMessage", (message) => {
  console.log("Сообщение отправлено:", message);
});

onChatError

Вызывается при возникновении ошибки при генерации ответа.

window.WikilectWidget.on("onChatError", (error) => {
  console.log("Ошибка генерации ответа:", error);
});

onChatReconnect

Вызывается при переподключении к чату.

window.WikilectWidget.on("onChatReconnect", () => {
  console.log("Переподключение к чату");
});

onUserLogOut

Пользователь разлогинился в чате из-за ошибки или вызова api.

window.WikilectWidget.on("onUserLogOut", () => {
  console.log("Пользователь разлогинился в чате");
});

onProductsReceived

Вызывается при получении товаров для слайдера.

window.WikilectWidget.on("onProductsReceived", (products) => {
  console.log("Пользователю предложены товары", products);
});

onOfferClick

Вызывается при клике пользователя по продукту из слайдера.

window.WikilectWidget.on("onOfferClick", (product) => {
  console.log("Пользователю кликнул по товару", product);
});