SDK Виджета

SDK Виджета Chatim позволяет встраивать и программно управлять виджетом чата Chatim на вашем веб-сайте.

Установка

Добавьте следующий код на ваш веб-сайт, непосредственно перед закрывающим тегом </body>:

<script>
  window.chatim = window.chatim || {};
  window.chatim.cmd = window.chatim.cmd || [];
  window.chatim.settings = { projectId: "YOUR_PROJECT_ID" };
</script>
<script src="https://widget.chatim.app/widget.js" async></script>

Замените YOUR_PROJECT_ID на фактический ID вашего проекта из панели управления Chatim.

Параметры конфигурации

Настройте виджет, установив свойства на window.chatim.settings:

window.chatim.settings = {
  projectId: "YOUR_PROJECT_ID",  // Required
  params: {                       // Optional: Custom parameters
    userId: "user-123",
    utm_source: "google",
    utm_campaign: "summer_sale"
  }
};

JavaScript API

Открытие виджета

window.chatim.widget.open();

Закрытие виджета

window.chatim.widget.close();

Установка конфигурации виджета

window.chatim.widget.setConfig(config);

Динамически обновляет конфигурацию виджета во время выполнения.

Получение конфигурации виджета

const config = window.chatim.widget.getConfig();

Возвращает текущий объект конфигурации или null, если виджет ещё не инициализирован.

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

window.chatim.widget.setParams({
  lastPage: "/checkout",
  cartValue: 99.99,
  isPremium: true
});

Обновляет пользовательские параметры после инициализации виджета. Параметры объединяются с существующими значениями (не заменяются).

Перезапуск чата

window.chatim.widget.restartChat();

Очищает все сохранённые данные и историю чата, закрывает виджет и повторно инициализирует с новой сессией. Полезно, когда пользователь выходит из системы или вы хотите сбросить разговор.

Справочник API

window.chatim.settings

window.chatim.widget

Пользовательские параметры

Пользовательские параметры позволяют отправлять дополнительные данные о ваших посетителях в Chatim. Эти данные хранятся с сессиями чата и отображаются в панели Посетителей административной панели.

Сценарии использования

• Идентификация пользователя - Передача ID пользователя, email или идентификаторов учётной записи
• Маркетинговая атрибуция - Отслеживание UTM параметров и источников кампаний
• Данные электронной коммерции - Отправка стоимости корзины, категорий товаров или истории покупок
• Сегментация пользователей - Включение типа плана, статуса подписки или уровня пользователя

Установка параметров при инициализации

window.chatim.settings = {
  projectId: "YOUR_PROJECT_ID",
  params: {
    userId: "user-123",
    email: "[email protected]",
    utm_source: "google",
    planType: "premium",
    isPremium: true
  }
};

Обновление параметров во время выполнения

// Update params when user logs in
window.chatim.widget.setParams({
  userId: user.id,
  email: user.email,
  planType: user.subscription
});

// Track page-specific data
window.chatim.widget.setParams({
  lastPage: window.location.pathname,
  productViewed: "SKU-12345"
});

Поддерживаемые типы данных

Не поддерживается: Объекты, массивы, функции, undefined

Правила именования параметров

• Начинать с буквы или подчёркивания
• Только буквенно-цифровые + подчёркивание
• Максимум 50 символов
• Зарезервированные имена: projectId, demo, __proto__, constructor, prototype

Ограничения

Просмотр параметров

Пользовательские параметры отображаются в панели управления Chatim в разделе Посетители - нажмите на посетителя, чтобы увидеть раздел Пользовательских параметров.

Автоматические URL параметры

Виджет может автоматически захватывать URL параметры со страниц посетителей без каких-либо изменений кода. Настройте это в Настройках виджета > URL параметры.

• Захватить все - Захватывает каждый валидный URL параметр
• Только белый список - Захватывает только указанные параметры (по умолчанию: utm_source, utm_medium, utm_campaign, utm_term, utm_content, ref)

Приоритет объединения

1. URL параметры (самый низкий приоритет)
2. window.chatim.settings.params (переопределяет URL параметры)
3. window.chatim.widget.setParams() (самый высокий приоритет)

Очередь команд

SDK включает очередь команд, которая позволяет вызывать методы виджета до полной загрузки виджета. Команды автоматически выполняются, когда виджет готов.

Формат функции (Рекомендуется)

window.chatim.cmd.push(function() {
  window.chatim.widget.close();
});

window.chatim.cmd.push(() => {
  window.chatim.widget.open();
  console.log('Widget opened!');
});

Поставить команды в очередь до загрузки виджета

<script>
  window.chatim = window.chatim || {};
  window.chatim.cmd = window.chatim.cmd || [];
  window.chatim.settings = { projectId: "YOUR_PROJECT_ID" };

  // Queue a function to run when widget is ready
  window.chatim.cmd.push(() => {
    console.log('Widget is ready!');
    window.chatim.widget.close();
  });
</script>
<script src="https://widget.chatim.app/widget.js" async></script>

Типичные сценарии использования

Открыть виджет при нажатии кнопки

<button onclick="window.chatim.widget.open()">
  Chat with us
</button>

Открыть виджет при прокрутке до низа

window.addEventListener('scroll', function() {
  if ((window.innerHeight + window.scrollY) >= document.body.offsetHeight) {
    window.chatim.widget.open();
  }
});

Перезапустить чат при выходе из системы

function onUserLogout() {
  window.chatim.widget.restartChat();
}

Открыть виджет с задержкой

setTimeout(function() {
  window.chatim.widget.open();
}, 5000);

Примеры интеграции SPA

React

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    window.chatim = window.chatim || {};
    window.chatim.cmd = window.chatim.cmd || [];
    window.chatim.settings = {
      projectId: 'YOUR_PROJECT_ID',
      params: { userId: getCurrentUserId() }
    };

    const script = document.createElement('script');
    script.src = 'https://widget.chatim.app/widget.js';
    script.async = true;
    document.body.appendChild(script);

    return () => document.body.removeChild(script);
  }, []);

  return <button onClick={() => window.chatim.widget.open()}>Open Chat</button>;
}

Next.js

'use client';

import { useEffect } from 'react';
import Script from 'next/script';

export default function ChatWidget() {
  useEffect(() => {
    window.chatim = window.chatim || {};
    window.chatim.cmd = window.chatim.cmd || [];
    window.chatim.settings = { projectId: 'YOUR_PROJECT_ID' };
  }, []);

  return (
    <Script
      src="https://widget.chatim.app/widget.js"
      strategy="lazyOnload"
    />
  );
}

Vue.js

export default {
  mounted() {
    window.chatim = window.chatim || {};
    window.chatim.cmd = window.chatim.cmd || [];
    window.chatim.settings = { projectId: 'YOUR_PROJECT_ID' };

    const script = document.createElement('script');
    script.src = 'https://widget.chatim.app/widget.js';
    script.async = true;
    document.body.appendChild(script);
  },
  methods: {
    openChat() {
      window.chatim.widget.open();
    }
  }
}

Пример интеграции электронной коммерции

// On page load
window.chatim.settings = {
  projectId: "YOUR_PROJECT_ID",
  params: {
    userId: getUserId(),
    userType: isLoggedIn() ? "registered" : "guest",
    utm_source: getUrlParam("utm_source")
  }
};

// On product view
function trackProductView(product) {
  window.chatim.widget.setParams({
    lastProductViewed: product.name,
    lastProductPrice: product.price
  });
}

// On add to cart
function trackAddToCart(cart) {
  window.chatim.widget.setParams({
    cartValue: cart.total,
    cartItems: cart.items.length
  });
}

Поддержка устаревших версий

Для обратной совместимости эти устаревшие API всё ещё поддерживаются:

// Legacy settings (still works)
window.chatimSettings = { projectId: "YOUR_PROJECT_ID" };

// Legacy widget methods (still works)
window.chatimWidget.open();
window.chatimWidget.close();

Мы рекомендуем использовать новое пространство имён window.chatim для всех новых реализаций.

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

Виджет не появляется

1. Проверьте правильность projectId
2. Проверьте консоль браузера на наличие ошибок
3. Убедитесь, что скрипт загружается (проверьте вкладку Сеть)
4. Убедитесь, что блокировщики рекламы не мешают

Команды не выполняются

1. Убедитесь, что window.chatim и window.chatim.cmd инициализированы перед вызовом методов
2. Проверьте правильность URL скрипта виджета
3. Проверьте, что скрипт успешно загрузился

getConfig возвращает Null

getConfig() возвращает null до полной инициализации виджета. Используйте подход опроса:

const checkWidget = setInterval(() => {
  const config = window.chatim.widget.getConfig();
  if (config) {
    clearInterval(checkWidget);
    console.log('Widget config:', config);
  }
}, 100);

Нужна помощь?

Если вам нужна помощь с интеграцией SDK, обратитесь по адресу [email protected].