Entegrasyon
Sohbet widget’ı
Widget, sitenize tek bir script etiketiyle eklenir ve sayfanızın stillerinden etkilenmemesi için kapalı bir Shadow DOM içinde çalışır.
#Kurulum
Kurulum kodunu yönetim panelinde Web siteleri ve widget sayfasından kopyalayın ve her sayfada </body> etiketinden önce ekleyin. Kod async yüklenir; sayfanızın açılışını bekletmez.
<script src="https://cdn.2people.chat/widget.js" async
data-widget-key="wk_0123456789abcdef0123456789abcdef0123"
data-api-url="https://api.2people.chat"
data-realtime-url="wss://rt.2people.chat/ws"
data-locale="tr"></script>#Öznitelikler
| Ad | Tür | Açıklama |
|---|---|---|
data-widget-keyzorunlu | wk_… | Web sitesinin widget anahtarı: wk_ ve 36 küçük harf onaltılık karakter. Yönetim panelindeki kurulum kodunda yer alır. |
data-api-urlzorunlu | https://… | Core API adresi (http veya https). Kurulum kodundaki değeri kullanın. |
data-realtime-urlzorunlu | wss://… | Gerçek zamanlı bağlantı (WebSocket) adresi (ws veya wss). Kurulum kodundaki değeri kullanın. |
data-locale | tr | en | Arayüz dili. Verilmezse tarayıcı dili kullanılır (Türkçe ise tr, aksi hâlde en). tr veya en dışında bir değer gelirse web sitesinin varsayılan dili uygulanır. |
data-theme | light | dark | system | Renk teması. Verilmezse web sitesi ayarı, o da yoksa system (ziyaretçinin işletim sistemi tercihi) kullanılır. |
data-position | right | left | Sohbet baloncuğunun köşesi. Verilmezse web sitesi ayarı, o da yoksa right kullanılır. |
Sayfada açıkça verilen data-locale, data-theme ve data-position değerleri her zaman web sitesi ayarlarından önceliklidir.
#JavaScript API’si
Widget yüklendikten sonra window.TwoPeople nesnesi tanımlanır. Kendi düğmenizden sohbeti açmak gibi işler için kullanabilirsiniz:
// window.TwoPeople is available once the widget has loaded.
window.TwoPeople.open(); // open the chat window
window.TwoPeople.close(); // close it
window.TwoPeople.toggle(); // open or close
window.TwoPeople.setTheme('dark'); // 'light' | 'dark' | 'system'
window.TwoPeople.destroy(); // remove the widget from the page| Yöntem | Açıklama |
|---|---|
open() · close() · toggle() | Sohbet penceresini açar, kapatır veya durumunu değiştirir. |
setTheme(theme) | Temayı değiştirir; bu değer web sitesi ayarından önceliklidir. |
identify(token) | Ziyaretçiyi giriş yapmış oyuncuya bağlar; Promise<boolean> döner. Bkz. Oyuncu kimliği. |
setConsent(granted) | Analitik onayını bildirir (aşağıya bakın). |
destroy() | Widget’ı sayfadan kaldırır. |
#Görünüm ve metinler
Yönetim panelinde web sitesinin Widget görünümü sayfasında şu ayarlar bulunur; değişiklikler canlı önizlemede görünür:
- Ana renk: başlık, baloncuk, düğmeler ve ziyaretçi mesajları için. Panel, rengin okunabilirliğini WCAG kontrastına göre denetler; widget metin rengini (beyaz ya da koyu) otomatik seçer.
- Konum (sağ alt / sol alt), tema ve varsayılan dil (TR/EN).
- Dil başına metinler: başlık, karşılama mesajı, mesai dışı notu ve memnuniyet sorusu. Boş bırakılan metinler için widget’ın yerleşik metinleri kullanılır.
- Memnuniyet (CSAT): konuşma kapandığında ziyaretçiden 1–5 arası puan ve isteğe bağlı yorum istenir. Puan 24 saat içinde değiştirilebilir.
Ziyaretçiler sohbete PNG, JPEG, GIF, WebP veya PDF dosyası (en fazla 10 MB) ekleyebilir.
#Mesai saatleri
Mesai saatleri yönetim panelinde Ekip ve erişim → Departmanlar ve çalışma saatleri bölümünde tanımlanır: tenant için bir saat dilimi ve haftalık program (ya da 7/24), istenirse departman başına ayrı program.
Hiçbir ekip mesaide değilken widget, görünüm ayarlarındaki mesai dışı notunu gösterir (not kapatılabilir). Ziyaretçi yine de mesaj yazabilir.
#Proaktif tetikleyiciler
Proaktif tetikleyiciler sayfasında, belirli koşullarda widget’ın ziyaretçiye kendiliğinden mesaj göstermesini sağlayabilirsiniz: URL içeriği, sayfada geçen süre, sayfa görüntüleme sayısı, yönlendiren adres, UTM kaynağı, yeni/geri dönen ziyaretçi ve cihaz. Her tetikleyicinin bir önceliği (0–1000) ve TR/EN mesajı vardır. Tetikleyiciler ziyaretçi analitiğine dayandığından yalnızca analitiğe izin verildiğinde çalışır.
#Onay ve gizlilik
Widget, sohbetten bağımsız olarak sayfa görüntüleme ve widget kullanımı gibi ziyaretçi analitiği toplayabilir. Gizlilik ve telemetri sayfasındaki politikada onay gerektir açıksa, analitik yalnızca onay verildikten sonra başlar. Global Privacy Control’a uyma seçeneği açıksa, GPC sinyali gönderen tarayıcılardan hiç analitik toplanmaz. Sohbetin kendisi onaydan etkilenmez.
Onayı çerez yönetim aracınızdan şu iki yoldan biriyle iletin:
<!-- Option A: after your consent banner accepts analytics -->
<script>
window.TwoPeople.setConsent(true);
</script>
<!-- Option B: consent already known when the page loads (before the widget script) -->
<script>
window.TwoPeopleConsent = true;
</script>
<script src="…/widget.js" async data-widget-key="…"></script>Onay geri çekilirse window.TwoPeople.setConsent(false) çağırın; bekleyen olaylar silinir ve toplama durur.
#İzin verilen kökenler
Widget yalnızca web sitesine kayıtlı kökenlerde oturum açabilir:
- Kayıtlı alan adı ve tüm alt alan adları, https üzerinden (ör.
example.comiçinhttps://www.example.com). localhostve127.0.0.1için http de kabul edilir.- Ek kaynaklar listesindeki tam kökenler (şema, alan adı ve port birebir eşleşmelidir).
Ziyaretçi oturumu açıldığı kökene bağlanır; başka bir kökenden gelen istekler reddedilir.
#Content Security Policy
Sitenizde CSP kullanıyorsanız widget’ın yaptıklarına izin verin: script dosyasını yükler, Core API’ye HTTP istekleri gönderir, gerçek zamanlı adrese WebSocket bağlantısı açar, görsel ekleri blob: adresleriyle gösterir ve stillerini Shadow DOM içine bir <style> öğesi olarak ekler. Örnek (kendi politikanızla birleştirin):
Content-Security-Policy:
script-src 'self' https://cdn.2people.chat;
connect-src 'self' https://api.2people.chat wss://rt.2people.chat;
img-src 'self' blob:;
style-src 'self' 'unsafe-inline';