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].