uHamkorHujjatlar
API hujjatlari

Chat Widget: ulash, sozlash va boshqarish

Chat widget’ni saytga ulash, tashqi ko‘rinishini va xatti-harakatlarini sozlash bo‘yicha qo‘llanma. Script atributlari (data-launcher, data-greeting, data-open), Shadow DOM izolyatsiyasi, CSS o‘zgaruvchilari va ::part() selektorlari, hamda window.uHamkor JavaScript API — metodlar, holat snapshot’i, hodisalar va amaliy retseptlar. Accessibility, print va reduced-motion qo‘llab-quvvatlanadi.

🎨 Chat Widget: ulash, sozlash va boshqarish

Widget saytga bitta <script> tegi orqali ulanadi, Shadow DOM yordamida stillarni izolyatsiya qiladi va CSS custom properties, ::part() selektorlari hamda window.uHamkor JavaScript API orqali boshqariladi.

🚀 Ulash

<script
  src="https://your-widget-host.com/widget.js"
  data-project-uuid="YOUR_PROJECT_UUID"
  data-language="uz"
  defer
></script>

Tegni sahifaning <head> qismiga qo‘ying. Widget faqat loyihaning domains ro‘yxatiga kiritilgan domenlarda ishga tushadi.

⚙️ Script atributlari

  • data-project-uuid — majburiy. Widget qaysi loyihaga tegishli ekanini bildiradi.
  • data-language — uz / ru / en. Standart: uz.
  • data-user — tashqi foydalanuvchi ID’si (tashrifchini identifikatsiya qiladi).
  • data-launcher — true / false. Standart: true. Suzuvchi tugmani chizadi.
  • data-greeting — true / false. Standart: true. Salomlashish pufakchasi.
  • data-open — true / false. Standart: false. Mount bo‘lishi bilan chat oynasini ochadi.

data-language, data-user, data-launcher va data-greeting runtime’da kuzatiladi — atribut qiymatini o‘zgartirsangiz, widget darhol yangilanadi.

🎯 CSS Variables

Quyidagi o‘zgaruvchilarni .chat-widget klassida override qiling:

.chat-widget {
  /* Ranglar (HSL, hsl()siz) */
  --cw-primary: 221 83% 53%;
  --cw-secondary: 258 83% 66%;
  --cw-background: 0 0% 100%;
  --cw-foreground: 222.2 84% 4.9%;

  /* Joylashuv */
  --cw-z-index: 50;
  --cw-button-bottom: 20px;
  --cw-button-right: 20px;
  --cw-window-bottom: 20px;
  --cw-window-right: 20px;

  /* Burchak radiusi */
  --cw-radius: 1rem;
}

Chat oynasining balandligi --cw-window-bottom qiymatidan hisoblanadi, shuning uchun widgetni pastdan ko‘targaningizda oyna ekrandan chiqib ketmaydi.

🧩 ::part() Selectors

Ichki elementlarga style berish:

.chat-widget::part(button) {}
.chat-widget::part(window) {}
.chat-widget::part(header) {}
.chat-widget::part(body) {}
.chat-widget::part(footer) {}

🖨️ Print Behavior

Widget chop etish (print) paytida avtomatik yashiriladi. Qo‘shimcha sozlama talab qilinmaydi.

🎞️ Reduced Motion

prefers-reduced-motion: reduce tanlagan foydalanuvchilar uchun animatsiyalar avtomatik o‘chiriladi.

💡 Misollar

📍 Widget joylashuvini o‘zgartirish

.chat-widget {
  --cw-button-bottom: 100px;
  --cw-button-right: 30px;
  --cw-window-bottom: 100px;
  --cw-window-right: 30px;
}

🔝 Yuqori z-index (modal oynalardan ustida)

.chat-widget {
  --cw-z-index: 99999;
}

🚫 Muayyan sahifalarda yashirish

.no-chat .chat-widget {
  display: none;
}

🕹️ JavaScript API (window.uHamkor)

Widget mount bo‘lishi bilan global API’ni window.uHamkor ga chiqaradi. U orqali widgetni o‘z UI’ingizdan boshqarasiz: header tugmasi, “Qo‘llab-quvvatlash” havolasi, o‘qilmagan xabarlar badge’i va h.k.

📦 Buyruqlar navbati (queue) bilan ulash

widget.js yuklanib bo‘lgunga qadar qilingan chaqiruvlar navbatga olinadi va yuklangach qayta ijro etiladi — setTimeout bilan kutish shart emas:

<script>
  window.uHamkor = window.uHamkor || function () {
    (window.uHamkor.q = window.uHamkor.q || []).push(arguments);
  };
  uHamkor('hideLauncher'); // sayt o‘z tugmasini chizadi
</script>
<script
  src="https://your-widget-host.com/widget.js"
  data-project-uuid="YOUR_PROJECT_UUID"
  data-language="uz"
  data-launcher="false"
  defer
></script>

Yuklangandan keyin ikkala chaqiruv uslubi ham ishlaydi:

uHamkor.open();   // metod ko‘rinishi
uHamkor('open');  // buyruq ko‘rinishi (navbat ham shuni ishlatadi)

🛠️ Metodlar

  • open() / close() / toggle() — chat oynasini boshqarish.
  • isOpen() — oyna ochiqmi (boolean).
  • showLauncher() / hideLauncher() — suzuvchi tugmani ko‘rsatish/yashirish. Chat ochiq bo‘lganda tugma yopish tugmasi sifatida ko‘rinib turadi.
  • setGreetingEnabled(enabled) — salomlashish pufakchasini yoqish/o‘chirish.
  • setLanguage(lang) — en, ru, uz, uz_latn, uz_cyrl.
  • getLanguage() — joriy til.
  • identify(identity) — { externalUserId, firstName, lastName, phoneNumber }.
  • logout() — sessiya, token va keshlangan xabarlarni tozalaydi.
  • prefill(text) — matnni yubormasdan input maydoniga qo‘yadi.
  • sendMessage(text) — xabar yuboradi; Promise<boolean> qaytaradi (false — yuborilmadi).
  • getUnreadCount() — o‘qilmagan xabarlar soni.
  • getState() — to‘liq holat snapshot’i.
  • subscribe(listener) — har bir holat o‘zgarishida ishlaydi; unsubscribe funksiyasini qaytaradi.
  • on(event, handler) / once / off — hodisalarga obuna.
  • setPosition({ bottom, right }) — tugma va oynani ko‘chiradi (piksel).
  • setColors(primary, secondary?) — ranglarni runtime’da almashtiradi.
  • destroy() — widgetni unmount qiladi va sahifadan olib tashlaydi.

📊 Holat snapshot’i

{
  projectUuid: string;
  isOpen: boolean;
  isLauncherVisible: boolean;
  isWidgetEnabled: boolean;   // loyihada widget o‘chirilgan bo‘lsa false
  unreadCount: number;
  language: string;
  isAuthorized: boolean;
  externalUserId: string | null;
  isTyping: boolean;          // operator/bot yozmoqda
  isOnline: boolean;          // qo‘llab-quvvatlash tomoni onlayn
  isBotActive: boolean;       // suhbatda jonli operator yo‘q
  isAIThinking: boolean;
  isResolved: boolean;
  callStatus: 'idle' | 'calling' | 'incoming' | 'active' | 'ended' | 'failed';
  callType: 'audio' | 'video';
}

📡 Hodisalar

  • ready — widget tayyor; payload: snapshot.
  • state — snapshot’ning istalgan maydoni o‘zgardi.
  • open / close — payload yo‘q.
  • unread — { count }.
  • message — { direction: 'incoming' | 'outgoing', message }.
  • operator:joined — operator suhbatga qo‘shildi.
  • chat:resolved — suhbat yakunlandi.
  • call:incoming / call:started / call:ended — { type }.
  • language:change — { language }.
  • identify — { externalUserId }.
  • destroy — widget o‘chirildi.

Har bir hodisa document ustida ham uhamkor:<event> nomi bilan yuboriladi, shuning uchun framework’lar global obyektga tegmasdan tinglashi mumkin:

document.addEventListener('uhamkor:unread', e => {
  badge.textContent = e.detail.count;
});

🍳 Amaliy retseptlar

🔔 O‘z tugmangiz va o‘qilmagan xabarlar badge’i

uHamkor('hideLauncher');
uHamkor('on', 'state', state => {
  badge.hidden = state.unreadCount === 0;
  badge.textContent = state.unreadCount;
  trigger.setAttribute('aria-expanded', String(state.isOpen));
});
trigger.addEventListener('click', () => uHamkor.toggle());

👤 Tizimga kirgan foydalanuvchini biriktirish

uHamkor.identify({
  externalUserId: user.id,
  firstName: user.firstName,
  lastName: user.lastName,
  phoneNumber: user.phone,
});

💬 Sahifadagi amaldan suhbat boshlash

uHamkor.open();
uHamkor.sendMessage('Menga #1234 buyurtma bo‘yicha yordam kerak');

🚪 Chiqishda sessiyani tozalash

uHamkor.logout();

🔄 Widget xatti-harakati

  • Suzuvchi tugmani sudrab (drag) ko‘chirish mumkin. Chat ochilganda tugma standart burchakka qaytadi va sudrash o‘chiriladi — shunda u oyna bilan bir tekisda turadi.
  • Chat ochiq bo‘lganda tugma yashirilmaydi: u yopish (close) tugmasi vazifasini bajaradi.
  • Salomlashish pufakchasi chat ochilganda yashiriladi.
  • Ochilish/yopilish animatsiyalari bosqichma-bosqich (header → xabarlar → input) ishlaydi; prefers-reduced-motion da o‘chadi.
  • Boshlang‘ich salomlashish xabari o‘qilgan deb belgilanadi, shuning uchun unreadCount faqat haqiqiy yangi xabarlarda o‘sadi.
  • setPosition({ bottom }) tugma bilan birga oyna joylashuvini ham moslaydi.

♿ Accessibility

  • Chat oynasida role="dialog" va aria-modal="true".
  • Barcha interaktiv tugmalarda aria-label.
  • Suzuvchi tugmada aria-haspopup="dialog".
  • Klaviatura bilan navigatsiya qo‘llab-quvvatlanadi.