Web Sitesi Widget'ları
Sesli ajanınızı herhangi bir web sitesine yerleştirin; böylece ziyaretçiler doğrudan tarayıcıdan bir sesli görüşme başlatabilir. Widget'lar sekmesi, yerleştirme kodları, özelleştirme seçenekleri ve alan adı güvenlik ayarları sağlar.
Geri Arama Widget'ı, bu sayfadaki widget'lardan çok farklı çalışır — tarayıcıda bir sesli çağrı başlatmak yerine, ziyaretçinin telefon numarasını toplar ve ajanınızın onları geri aramasını sağlar. Özel Geri Arama Widget'ı sayfasına bakın.
Widget Türleri
Hanc.AI, telefon geri aramaları için ayrı bir Geri Arama Widget'ı'na ek olarak dört tarayıcı içi widget türü sunar:
| Widget | Etiket Adı | Açıklama | En Uygun |
|---|---|---|---|
| Yüzen Widget | hanc-ai-floating-call | Sayfanızın üzerinde yüzen küre düğmesi | Her zaman görünür eylem çağrısı |
| Hap Widget | hanc-ai-pill-call | İçeriğinizde satır içi yerleştirilen kompakt hap şeklinde düğme | Mevcut bir düzen içinde minimal alan |
| Yüzen Hap Widget | hanc-ai-pill-floating-call | Hap ile aynı kompakt hap şekli, ancak Yüzen widget gibi sayfayla yüzer | Ziyaretçi kaydırdıkça takip eden bir hap estetiği istediğinizde |
| Satır İçi Widget | hanc-ai-inline-call | Sayfa içeriğine yerleştirilen tam boyutlu çağrı düğmesi | Özel "Bizimle Konuşun" bölümleri |
| Geri Arama Widget'ı | hanc-ai-callback | Telefon numarası formu; ajan ziyaretçiyi geri arar | Potansiyel müşteri toplama sayfaları, yüksek niyetli açılış sayfaları — bkz. Geri Arama Widget'ı |
Ortak Özellikler
Tüm widget türleri bu temel özellikleri destekler:
| Özellik | Zorunlu | Açıklama | Varsayılan |
|---|---|---|---|
agent-id | Evet | Ajanınızın benzersiz tanımlayıcısı | — |
voice-service-url | Hayır | Ses hizmeti URL'sini geçersiz kılın | Otomatik algılanır |
api-base-url | Hayır | API temel URL'sini geçersiz kılın | Otomatik algılanır |
Görüntüleme Özellikleri
| Özellik | Açıklama | Değerler | Varsayılan |
|---|---|---|---|
position | Sayfadaki widget konumu | bottom-right, bottom-left, top-right, top-left, static | bottom-right |
size | Piksel cinsinden widget boyutu | Sayı | 120 |
theme | Renk teması adı | Bkz. Renk Temaları | default |
Düğme Metni Özellikleri
| Özellik | Açıklama | Varsayılan |
|---|---|---|
button-start-text | Boştaki düğmede gösterilen metin | "Call" |
button-connecting-text | Bağlanırken gösterilen metin | "Connecting..." |
button-end-text | Etkin bir çağrı sırasında gösterilen metin | — |
Şartlar Özellikleri
| Özellik | Açıklama | Varsayılan |
|---|---|---|
terms-enabled | Çağrıdan önce onay iletişim kutusunu etkinleştir | false |
terms-content | Markdown biçimli onay metni | "" |
terms-url | Şartlar ve Koşullar sayfanıza bağlantı | "https://hanc.ai/terms" |
privacy-url | Gizlilik Politikası sayfanıza bağlantı | "https://hanc.ai/privacy" |
HTML öğesinde ayarlanan Şartlar özellikleri, skip-fetch true olarak ayarlanmadıkça, API'den getirilen ajanın widget ayarları tarafından geçersiz kılınır.
Ses Özellikleri
| Özellik | Açıklama | Varsayılan |
|---|---|---|
sound-enabled | Çağrı başlangıç/bitiş seslerini etkinleştir | true |
sound-volume | Ses efekti düzeyi | 0.25 |
sound-preset | Ses ön ayarı tanımlayıcısı | "1" |
Renk Temaları
Widget görünümünü 11 yerleşik renk temasıyla özelleştirin:
| Tema | Değer |
|---|---|
| Varsayılan | default |
| Mor | purple |
| Mavi | blue |
| Camgöbeği | cyan |
| Zümrüt | emerald |
| Kehribar | amber |
| Mandalina | tangerine |
| Gül | rose |
| Köz | ember |
| Siyah | black |
| Beyaz | white |
Her temanın hem koyu hem de açık varyantı vardır. Temayı yerleştirme kodundaki theme özelliği aracılığıyla ayarlayın veya ajanın widget ayarlarında yapılandırın.
Yerleştirme Örnekleri
Yüzen Widget
<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Tema ve Konumla Yüzen Widget
<hanc-ai-floating-call
agent-id="YOUR_AGENT_ID"
theme="emerald"
position="bottom-left"
size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Hap Widget
<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Satır İçi Widget
<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Yukarıdaki betik URL'si her zaman en son yayınlanan widget'ı yükler — siteniz iyileştirmeleri otomatik olarak alır ve bir sürüm belirtilmediğinde @latest varsayılandır. Sabit bir sürüme kilitlemeniz gerekiyorsa, istediğiniz sürümü ekleyerek açıkça sabitleyin, ör. https://unpkg.com/hanc-webrtc-widgets@X.Y.Z.
Widget Olayları
Widget'lar, JavaScript'te dinleyebileceğiniz olaylar yayar:
| Olay | Açıklama |
|---|---|
status-changed | Çağrı durumu değiştiğinde tetiklenir |
connecting | Çağrı kuruluyor |
connected | Çağrı etkin |
idle | Etkin çağrı yok |
error | Bir hata oluştu |
audio-track | Uzak ses parçası alındı (görselleştirme için) |
local-audio-track | Yerel mikrofon ses parçası (görselleştirme için) |
microphone-enabled | Mikrofon etkinleştirildi |
microphone-disabled | Mikrofon devre dışı bırakıldı |
call-start | Bir çağrı başarıyla başladığında tetiklenir |
call-end | Çağrı bittiğinde tetiklenir |
Örnek: Olayları Dinleme
const widget = document.querySelector('hanc-ai-floating-call');
widget.addEventListener('call-start', () => {
console.log('Call started');
});
widget.addEventListener('call-end', () => {
console.log('Call ended');
});
Temsilcinin sayfa açmasına izin verme
Tarayıcı üzerinden bir görüşme sırasında temsilci sitenizden bir sayfayı açmasını isteyebilir — «fiyatları göstereyim» — ve ziyaretçi bunu konuşmayı kesmeden görür.
Karar sizin sayfanızındır. Temsilci bir istek gönderir, ne anlama geldiğine kodunuz karar verir. Bir adresi açmak, sekme değiştirmek, bir bölüme kaydırmak, akordeonu açmak — hepsi geçerli yanıtlardır.
Üç adım gerekir ve hiçbiri tek başına işe yaramaz.
1. adım — Temsilciye hangi sayfaların olduğunu söyleyin
Temsilci sitenizin haritasını görmez. Yalnızca kendisine verdiğiniz yolları ister; bunları temsilcinin prompt'unda veya bilgi tabanında listeleyin:
Sitemizdeki sayfalar:
/pricing — paketler ve fiyatlar
/contact — iletişim formu ve telefon
/product/crm — CRM
Bu adım olmadan temsilcinin isteyeceği bir şey yoktur, dolayısıyla denemez bile.
2. adım — İsteği sayfanızda karşılayın
Bunu bir kez, widget betiğinden sonra herhangi bir yere ekleyin. Olay sayfada yukarı doğru kabarır, bu yüzden document dinlemek için uygun bir yerdir:
<script>
document.addEventListener('agent-command', (event) => {
const { type, payload } = event.detail;
if (type === 'navigate') {
// SPA: yeniden yüklemeden yönlendirin — görüşme devam eder.
router.push(payload.path);
// Klasik site: ikinci bir sekme açın, böylece bu sekme (ve görüşme) ayakta kalır.
// window.open(payload.path, '_blank');
event.preventDefault(); // ← temsilciye «hallettim» diyen budur
}
});
</script>
Görüşme bu sayfanın içinde yaşar. window.location.href = … belgeyi boşaltır ve konuşma da onunla gider — ziyaretçi cümlenin ortasında kesilir. Router'ınız varsa istemci tarafında yönlendirin; yoksa sayfayı yeni bir sekmede açın. Yeniden bağlanma yoktur: yeniden yüklemeden hiçbir şey sağ çıkmaz.
preventDefault() isteğe bağlı değildir«Ben hallettim» demenin tek yolu budur. Olmadığında temsilciye sitenin gezinmeyi desteklemediği bildirilir: görüşmenin geri kalanında denemeyi bırakır ve nereye tıklanacağını anlatmaya döner. Konsolda hiçbir şey görünmez — sayfa yalnızca isteği yok saymış gibi görünür, çünkü öyle yapmıştır.
3. adım — Deneyin
Siteden temsilcinizi arayın ve bir sayfayı adıyla isteyin. İki şey olmalı: sayfa açılır ve temsilci «menüde bulabilirsiniz» yerine «işte fiyatlar» gibi bir şey söyler.
Temsilciye veriyle yanıt verme
Bazı komutlar talimat değil, sorudur. Aynı şekilde gelirler ama respond() ile yanıtlanırlar:
| Komut | Temsilci ne soruyor | Neyle yanıtlarsınız |
|---|---|---|
navigate | «bu yolu aç» | hiçbir şeyle — preventDefault() yeterli |
page_context | «ziyaretçi neye bakıyor?» | işe yarayan her şeyle: yol, başlık, ürün |
cart_state | «sepetinde ne var?» | kalemler, toplamlar, para birimi |
<script>
document.addEventListener('agent-command', (event) => {
const { type, respond } = event.detail;
if (type === 'page_context') {
event.preventDefault();
respond({ path: location.pathname, title: document.title });
}
});
</script>
preventDefault() sonrasında yanıt için yaklaşık bir saniyeniz var: await sorun değil, yavaş bir API çağrısı sorun. Zaten elinizde olanla yanıt verin.
Temsilci neyi isteyebilir, neyi isteyemez
- Yalnızca kendi sitenizdeki yollar. Yol
/ile başlamalıdır. Alan adınızın dışına çıkabilecek her şey —//evil.com,https://…, ters bölü işaretleri — sayfanıza ulaşmadan reddedilir. Bir temsilci ziyaretçilerinizi başka bir yere gönderemez. - Yalnızca tarayıcı görüşmeleri. Telefon görüşmesinde açılacak bir sayfa yoktur, orada bu komutlar bulunmaz.
- Bir ret yeter. Sayfanız ilk isteği onaylamazsa temsilci görüşmenin geri kalanında sormayı bırakır. Yeniden denemez ve — daha önemlisi — ziyaretçiye açmadığı bir şeyi açtığını söylemez.
Filtrelemeden önce her komutu günlüğe yazın: document.addEventListener('agent-command', e => console.log(e.detail)). Konsolda navigate görüyorsanız temsilci üzerine düşeni yapmıştır; eksik olan preventDefault() ya da kendi işleyicinizdir. Hiçbir şey görmüyorsanız temsilciye böyle bir yolun var olduğu hiç söylenmemiştir — 1. adıma dönün.
Teknik Gereksinimler
Widget'lar, ziyaretçinin tarayıcısının şunları desteklemesini gerektirir:
- WebGL 2.0 — oluşturma için
- Web Audio API — ses işleme için
- WebRTC — gerçek zamanlı sesli iletişim için
Tüm modern tarayıcılar (Chrome, Firefox, Safari, Edge) bu teknolojileri destekler.
Alan Adı Kısıtlamaları
Hangi web sitelerinin ajan widget'ınızı yerleştirebileceğini kontrol edin.
Her Zaman İzin Verilen Alan Adları
Aşağıdaki alan adlarına yapılandırmadan bağımsız olarak her zaman izin verilir:
hanc.ai(ve alt alan adları)hanc.me(ve alt alan adları)localhost
Tüm Alan Adlarına İzin Ver
Varsayılan olarak, widget'ınız herhangi bir web sitesine yerleştirilebilir. Bunu kısıtlamak için widget ayarlarında "Tüm alan adlarına izin ver" düğmesini açıp kapatın.
Belirli Alan Adlarıyla Kısıtla
Kısıtlandığında, izin verilmesi gereken her alan adını ekleyin:
- Alan adlarını
https://olmadan girin (ör.example.com) - Alt alan adları ayrı girişler gerektirir (ör.
www.example.com,shop.example.com) - Bağlantı noktaları belirtilebilir (ör.
localhost:3000) - En fazla 50 alan adı beyaz listeye alınabilir
Üretim ajanları için, yetkisiz yerleştirmeyi önlemek amacıyla widget'ları kendi alan adlarınızla kısıtlayın.
Şartlar ve Koşullar
Arayanlar bir görüşme başlatabilmeden önce bir onay iletişim kutusunu etkinleştirin.
Yapılandırma
| Ayar | Açıklama |
|---|---|
| Şartları Etkinleştir | Şartlar iletişim kutusunu aç/kapat |
| Şartlar İçeriği | Kullanıcılara gösterilen Markdown biçimli onay metni (en fazla 5.000 karakter) |
| Şartlar URL'si | Tam Şartlar ve Koşullar sayfanıza bağlantı |
| Gizlilik URL'si | Gizlilik Politikası sayfanıza bağlantı |
Etkinleştirildiğinde:
- Kullanıcılar bir çağrı başlatmadan önce bir onay iletişim kutusu görür
- Devam etmek için "Kabul Et" düğmesine tıklamaları gerekir
- Onay, tarayıcıda yerel olarak saklanır
- Onayı Sıfırla düğmesi, test için saklanan onayı temizler
İçerik Biçimlendirme
Şartlar içeriği Markdown biçimlendirmesini destekler:
- Başlıklar için
####kullanın - Vurgu için
**kalın**kullanın - Okunabilirlik için satır sonları kullanın
İlgili
- Geri Arama Widget'ı — Tarayıcıda konuşmayı tercih etmeyen ziyaretçiler için telefon geri aramaları
- Sesli Ajanlara Genel Bakış
- Ayarlar — Widget yapılandırması dahil ajan ayarları
- Entegrasyonlar — API anahtarları ve telefon numarası kurulumu