Site entegrasyonu

Panelde Kurulum sayfası, sitenizin widget anahtarı ve kanallarıyla doldurulmuş kodu hazır verir. Bu belge o kodun her parçasını açıklar.

#Nasıl çalışır

1. Sayfanıza eklediğiniz jev-chat.js, sağ (veya sol) alt köşeye bir sohbet düğmesi çizer. Düğme Shadow DOM içindedir; sitenizin CSS'i onu, onun CSS'i sitenizi etkilemez.
2. Sohbetin kendisi ayrı bir alan adında, izole bir iframe içinde çalışır. Sayfanız sohbet içeriğine, sohbet de sayfanızın verisine erişemez. İkisi yalnızca doğrulanmış postMessage mesajlarıyla konuşur.
3. Ziyaretçi misafir olarak başlar. Giriş yapmış bir üyeyse sunucunuz kimliğini imzalar; imza doğrulanınca temsilci adı, e-postayı ve üyelik bilgisini doğrulanmış olarak görür.
4. Müşterinin sorularını önce asistan karşılar. İstediği an veya asistan yanıt veremediğinde görüşme bir temsilciye aktarılır.

#Hızlı başlangıç

Kodu sitenizin tüm sayfalarında </body> etiketinden hemen önce ekleyin:

<script type="module" src="https://widget.talkvelo.com/jev-chat.js"
  data-widget-key="wk_SITE_ANAHTARINIZ"
  data-channel="web"
  async></script>

• widget.talkvelo.com ve widget anahtarı panelde Kurulum sayfasında yazar.
• Widget anahtarı gizli değildir; yalnızca hangi sitenin sohbeti olduğunu belirtir, tek başına hiçbir yetki vermez.
• Sitenizin adresi (ör. https://www.siteniz.com) anahtarın izinli adresler listesinde olmalıdır. Listede olmayan bir adreste widget oturum açamaz; böylece anahtarınızı kopyalayan başka bir sayfa sizin adınıza sohbet açamaz. Listeyi değiştirmek için hesap yöneticinize başvurun.
• Liste üç biçim kabul eder (en fazla 10 satır, yalnızca https):
• tam adres: https://www.siteniz.com
• numaralı aralık (ayna adresler): https://siteniz{100-1000}.com → siteniz100.com … siteniz1000.com (en fazla 5000 adres; başında sıfırlı numara eşleşmez)
• alt alan: https://*.siteniz.com → tek seviye alt alanlar (m.siteniz.com); siteniz.com'un kendisi ayrıca yazılır
• Aralıktaki her alan adı sizin olmalıdır. Sahibi olmadığınız bir numarayı başkası alırsa widget o sayfada da açılabilir. Kullanmadığınız numaraları aralığa katmayın.

#Etiket öznitelikleri

#Ayarlar: window.JevChatSettings

Etiketten önce tanımlanan bu nesneyle ziyaretçi bilgisi ve davranış ayarları verilir. Aynı ayar hem öznitelikte hem burada varsa buradaki geçerlidir.

<script>
  window.JevChatSettings = {
    channel: 'web',
    visitor: { name: 'Ad Soyad', email: '[email protected]' },
  };
</script>
<script type="module" src="https://widget.talkvelo.com/jev-chat.js" data-widget-key="wk_…" async></script>

#Ziyaretçi tipleri

İmzalı kimlikle gelen üye ve VIP, widget başlığındaki Önceki görüşmeler düğmesiyle son 180 günün görüşmelerini görür (farklı cihazda da). Misafire başka oturumların geçmişi gösterilmez. Temsilci iç notları görünmez.

VIP olmak ve doğrulanmış ad/e-posta göstermek yalnızca imzayla mümkündür. Sayfada yazan veya ziyaretçinin kendi girdiği bilgi hiçbir zaman doğrulanmış sayılmaz ve imzalı bilginin üzerine yazamaz.

#Giriş yapmış ve VIP üyeler: imzalı kimlik

Sunucunuz, sayfayı üretirken üyenin bilgisini JSON olarak yazar ve bu metni kendi secret değerinizle HMAC-SHA256 ile imzalar. Sayfaya yalnızca metin ve imza gelir; secret asla tarayıcıya gönderilmez.

#Payload alanları

İmza: signature = hex(HMAC_SHA256(secret, payload)). İmza, payload metninin kendisi üzerindedir: imzaladıktan sonra metni değiştirmeyin, yeniden serileştirmeyin.

#Node.js

import { createHmac } from 'node:crypto';

export function jevIdentity(user) {
  const payload = JSON.stringify({
    userId: String(user.id),
    name: user.fullName,
    email: user.email,
    segment: user.isVip ? 'vip' : 'member',
    attributes: { level: user.level },
    issuedAt: Math.floor(Date.now() / 1000),
  });
  const signature = createHmac('sha256', process.env.JEV_OPERATOR_SECRET).update(payload).digest('hex');
  return { payload, signature };
}

#PHP

<?php
$payload = json_encode([
  'userId'     => (string) $user->id,
  'name'       => $user->full_name,
  'email'      => $user->email,
  'segment'    => $user->is_vip ? 'vip' : 'member',
  'attributes' => ['level' => $user->level],
  'issuedAt'   => time(),
], JSON_UNESCAPED_UNICODE);
$jevIdentity = [
  'payload'   => $payload,
  'signature' => hash_hmac('sha256', $payload, getenv('JEV_OPERATOR_SECRET')),
];

#Python

import hashlib, hmac, json, os, time

payload = json.dumps({
    "userId": str(user.id),
    "name": user.full_name,
    "email": user.email,
    "segment": "vip" if user.is_vip else "member",
    "attributes": {"level": user.level},
    "issuedAt": int(time.time()),
}, ensure_ascii=False, separators=(",", ":"))
jev_identity = {
    "payload": payload,
    "signature": hmac.new(os.environ["JEV_OPERATOR_SECRET"].encode(), payload.encode(), hashlib.sha256).hexdigest(),
}

#Sayfada kullanım

<script>
  window.JevChatSettings = {
    identity: { payload: <?= json_encode($jevIdentity['payload']) ?>, signature: '<?= $jevIdentity['signature'] ?>' },
    onSessionExpired: () =>
      fetch('/api/jev-identity', { credentials: 'include' })
        .then((r) => r.json())
        .then((i) => window.JevChat.setIdentity(i)),
  };
</script>

/api/jev-identity sizin yazacağınız, oturum açmış üye için yukarıdaki fonksiyonu çağırıp { payload, signature } döndüren bir uç noktadır.

#Secret'ı saklama

• Secret değeri size güvenli kanaldan iletilir. Panelde yalnızca referans adı görünür, değeri görünmez.
• Secret'ı yalnızca sunucu ortam değişkeninde veya secret yöneticinizde tutun. Kaynak koda, sayfaya, mobil uygulamaya koymayın.
• Sızdığından şüphelenirseniz hesap yöneticinizden yenisini isteyin. Eski imzalar yeni secret'la geçersiz olur.

#Site oturum belirteci (secret'sız üye girişi)

Siteniz giriş yapmış üyeye zaten imzalı bir belirteç (JWT) veriyorsa, imza ucu yazmanıza gerek yoktur: belirteci olduğu gibi widget'a verin. İmzayı, süreyi ve üye numarasını TalkVelo sunucusu sizin açık anahtarınızla doğrular.

<script>
  window.JevChatSettings = { channel: 'members', siteToken: window.jwt };
</script>
<script type="module" src="https://widget.talkvelo.com/jev-chat.js" data-widget-key="wk_…" async></script>

Bizden istenen tek şey, belirteci doğrulayacak bilgi. Bunu platform ekibimiz tanımlar (panelde site yöneticisi giremez):

Kurallar:

• Belirteç exp taşımalıdır (süresi dolmuş belirteç kabul edilmez; ±60 sn saat farkı payı vardır). Sabit algoritma listesi dışındaki (ör. none) ve başka anahtarla imzalı belirteç reddedilir.
• Belirtecin payload'ı değiştirilirse imza tutmaz; ziyaretçi misafir açılır. Sayfadaki değişkenden okunan imzasız üye numarası hiçbir zaman doğrulanmış sayılmaz.
• Belirteç TalkVelo'da saklanmaz ve kayıtlara yazılmaz; yalnızca doğrulama sonucu kaydedilir. Ad ve e-posta belirteçten alınmaz, profil entegrasyonu üye numarasıyla doldurur.
• Giriş sonrası: JevChat.setSiteToken(jwt). Çıkış: JevChat.reset(). Belirteç yenilenirse aynı kişi için yeniden verebilirsiniz; açık görüşme kapanmaz.
• İsteğe bağlı siteTokenOrigin (veya setSiteToken(jwt, origin)): belirteci üreten sağlayıcının https adresi. Doğrulama henüz tanımlı değilken platform ekibi panelde belirtecin yalnızca alan adlarını ve bu adresi bilgi olarak görür (doğrulanmamış; ayara kendiliğinden aktarılmaz). Doğrulamada hiçbir rolü yoktur.

#Giriş ve çıkış anı

• Sayfa yenilenmeden giriş: JevChat.setIdentity({ payload, signature }) çağırın. Widget doğrulanmış yeni bir görüşme açar. Misafirken yazılanlar yeni kimliğe taşınmaz.
• Çıkış: sayfayı yenileyin veya JevChat.destroy() çağırıp etiketi yeniden yükleyin. Widget oturum bilgisini tarayıcıda saklamaz (localStorage/çerez yok); sayfa kapanınca oturum da kapanır.

#Sunucular arası oturum (isteğe bağlı)

Kimliği sayfaya hiç koymak istemiyorsanız, sunucunuz doğrudan platformdan kısa ömürlü bir oturum açabilir ve token'ı sayfaya verebilir.

POST /v1/widget/sessions/exchange
x-operator-timestamp: 1767225600
x-operator-signature: hex(HMAC_SHA256(secret, "1767225600." + gövde))
content-type: application/json

{ "widgetKey": "wk_…", "subjectRef": "uye_123", "authLevel": "verified", "issuedAt": 1767225600,
  "profile": { "name": "Ad Soyad", "email": "[email protected]", "segment": "vip" } }

• Zaman damgası ±5 dakika içinde olmalıdır. İmza, zaman damgası + nokta + ham gövde üzerindedir.
• Yanıttaki token'ı sayfada JevChat.setSession(token) ile verin. Süresi dolunca onSessionExpired çağrılır; yeni token alıp tekrar verin.

#JavaScript API: window.JevChat

<a href="#" onclick="window.JevChat?.open(); return false;">Canlı destek</a>

#Dil

Varsayılan dil Türkçedir; siteniz İngilizceyi de destekliyorsa (panelde Gelişmiş yapılandırma → Dil) widget iki dilde çalışır.

• Hangi dilde açılır: data-locale / locale verildiyse o dil; yoksa ziyaretçinin widget'ta daha önce seçtiği dil; yoksa sayfanızın <html lang="en"> değeri; yoksa sitenizin varsayılan dili.
• Dil düğmesi: sitede birden çok dil açıksa sohbet başlığında TR / EN düğmesi görünür. Ziyaretçinin seçimi widget'ın kendi depolamasında hatırlanır.
• Görüşme dili: asistan yanıtları, bilgi bankası makaleleri ve sistem bildirimleri görüşmenin dilindedir. Ziyaretçi görüşme sırasında dil değiştirirse sonraki yanıtlar yeni dilde gelir; önceki mesajlar olduğu gibi kalır.
• Panelden girilen metinler (başlık, karşılama, hazır sorular, duyuru bandı, görsel açıklaması) Widget görünümü → Metin dili: English ile girilir. İngilizce karşılığı girilmeyen alan İngilizce widget'ta Türkçe haliyle görünür.
• Çok dilli sitede dil değiştirme menünüzden window.JevChat?.setLocale('en-GB') çağırın.

#Tek sayfa uygulamaları (React, Vue, Next.js)

Etiketi uygulamanın kabuğuna bir kez ekleyin; her rota değişiminde yeniden eklemeyin. Geri/ileri ve # değişimleri otomatik algılanır. history.pushState ile yaptığınız geçişlerden sonra window.JevChat?.pageView() çağırın ki temsilci ziyaretçinin bulunduğu sayfayı doğru görsün.

#Kanallar (gruplar)

Kanallar ve hangi kuyruğa düştükleri panelde Gelişmiş yapılandırma altında tanımlanır; iki yöneticinin onayıyla yayınlanır.

Bir kanal ön form isteyecek şekilde ayarlanabilir: misafir ad soyad ve e-posta vermeden sohbet başlatamaz, yazamaz, dosya gönderemez ve temsilciye bağlanamaz (sunucu da reddeder). visitor ile verdiğiniz ad/e-posta formda sorulmaz; yalnızca eksik olan sorulur. Doğrulanmış üyelere form çıkmaz. Oyuncu koruma (limit, kendini dışlama) ve hesap güvenliği talepleri kanaldan bağımsız olarak her zaman ilgili uzman kuyruğuna gider.

#Çevrimiçi ziyaretçiler ve temsilcinin başlattığı görüşme

Widget sayfa boştayken arka planda yüklenir ve sayfa görünür olduğu sürece 30 saniyede bir "buradayım" bildirir. Temsilciler Ziyaretçiler ekranında sitedeki ziyaretçileri (sayfa, cihaz, sitede geçen süre, önceki görüşme sayısı) görür ve birine görüşme başlatabilir.

• Temsilci yazdığında sohbet düğmesinin üstünde "Ayşe size bir mesaj gönderdi" kartı çıkar. Mesaj içeriği sayfanıza verilmez, yalnızca temsilcinin adı gösterilir.
• Ziyaretçi zaten asistanla konuşuyorsa görüşme temsilciye geçer. Başka bir temsilciyle görüşüyor veya sırada bekliyorsa yeni görüşme başlatılamaz.
• Temsilcinin ilk mesajında bonus, kampanya veya promosyon ifadesi kullanılamaz. Proaktif mesaj pazarlama kanalı değildir.
• Sohbet açılmadan hiçbir görüşme kaydı oluşmaz; yalnızca ziyaretçi oturumu ve varlık bilgisi tutulur.
• Bu özelliği istemiyorsanız data-lazy="true" kullanın.

#Dosya ekleri

Panelde widget görünümüne başlığın altında kenardan kenara bir görsel bant eklenebilir (göster/gizle, ziyaretçi kapatabilir); görsel widget sunucusu üzerinden değil API'den yüklenir, sitenizin CSP'sinde ek izin gerekmez. Müşteri ve temsilci sohbette görsel (JPG, PNG, WebP, GIF), ses (MP3, M4A, OGG, WAV), video (MP4, WebM, MOV) ve PDF gönderebilir. Sınır görsel ve PDF için 10 MB, ses için 20 MB, video için 50 MB; müşteri aynı anda 3 dosya seçebilir. Görseller sohbette önizlenir ve tıklanınca yakınlaştırılabilir görüntüleyicide açılır; ses ve video tarayıcının oynatıcısıyla oynatılır. SVG, HTML ve ofis belgeleri güvenlik nedeniyle kabul edilmez. Dosyalar önce karantinaya alınır ve taranır. Yalnızca temiz çıkan dosya karşı tarafa açılır. Kimlik belgeleri için sohbet yerine hesabınızdaki güvenli belge yükleme ekranını kullandırın.

#İçerik güvenliği politikası (CSP)

Sitenizde CSP varsa şu kaynaklara izin verin (widget.talkvelo.com ve api.talkvelo.com panelde yazar):

script-src   https://widget.talkvelo.com
frame-src    https://widget.talkvelo.com
connect-src  https://api.talkvelo.com

Widget'ın kendi iframe'i ayrıca kendi CSP'siyle korunur; sitenizin ek bir şey yapması gerekmez.

#Gönderilen veriler

Widget çerez kullanmaz. Widget'ın kendi depolamasında (sizin sitenizin değil, widget adresinin localStorage'ı) yalnızca yukarıdaki cihaz kimliği (jev-device) ve dil seçimi (jev-lang) durur. Ziyaretçinin kapattığı duyuru bandı o sekme için hatırlanır (sessionStorage). Parmak izi (tarayıcı/donanım özellikleri) toplanmaz. Çerez/gizlilik politikanızda bu kimliği "güvenlik ve kötüye kullanımı önleme" amaçlı kesinlikle gerekli depolama olarak belirtebilirsiniz.

#Uygunsuz dil ve sohbet engeli

• Küfür, hakaret veya tehdit içeren mesaj kabul edilir ve temsilci ekranında işaretlenir. Ziyaretçi ilk seferde bir kez saygılı dil uyarısı görür.
• Engeli yalnızca ekibiniz verir (otomatik engel yoktur). Engellenen ziyaretçi widget'ı açınca yazma alanı yerine "Destek sohbetine erişiminiz kısıtlandı" kartını, bitiş zamanını ve sitenizin bilgi metnini görür (varsayılan: Sorumlu Oyun bölümünün yolu).
• Tanıma: imzalı kimlikle gelen üye üye numarasıyla tanınır (her cihazda geçerlidir). Misafir cihaz kimliğiyle tanınır; tarayıcı verisini silerse kimlik kaybolur. Bu durumlar için ekibiniz en fazla 24 saatlik IP engeli de ekleyebilir.
• Bu yüzden giriş yapmış üyeler için imzalı kimlik kullanmanız engellerin güvenilir çalışması için de önemlidir.

#Sorun giderme

#Canlıya almadan önce

• Etiket tüm sayfalarda, bir kez yükleniyor.
• Canlı alan adınız izinli adresler listesinde.
• İmzalı kimlik her sayfa yüklemesinde sunucuda yeniden üretiliyor; secret yalnızca sunucuda.
• Önbelleğe alınan sayfalarda imza yok (veya imza ayrı bir uç noktadan alınıyor).
• CSP izinleri eklendi.
• Test üyesiyle misafir, üye ve VIP akışları denendi; temsilci ekranında doğru rozetler görünüyor.