Ziyaretçileri tanımlama ve bağlam iletme

Web siteniz kimin geldiğini biliyorsa sohbete bildirin. Ekibiniz böylece panelde “Ziyaretçi 4f2a” yerine ad görür; müşteri verileri ve müşteri portalı gibi özellikler ancak bu şekilde mümkün olur.

İlke: Tarayıcı hiçbir şeyi kanıtlamaz. Sayfanın identify üzerinden iddia ettiği her şeyi herhangi bir ziyaretçi konsolda taklit edebilir. Kullanıcı yalnızca sunucunuzun, tarayıcıya asla ulaşmayan gizli anahtarla hesapladığı imzayla doğrulanmış sayılır.

Tarayıcıdaki çağrı

ReactiveChat('identify', {
  userId:   '4711',
  email:    'kim@example.com',
  name:     'Kim Berger',
  userHash: '9c1f…',
  exp:      1792503600
});

• userId (dize, önerilir) – kullanıcı için kendinize ait kalıcı kimlik. E-posta adresi veya değişebilecek sıralı numara değil.
• email (dize, isteğe bağlı) – panelde gösterilir. Yalnızca o da imzalandıysa doğrulanır (aşağıda).
• name (dize, isteğe bağlı) – paneldeki görünen ad.
• userHash (dize, doğrulama için zorunlu) – sunucunuzda hesaplanan 64 onaltılık karakter.
• exp (tam sayı, önerilir) – özetin son kullanma zamanı, Unix saniyesi olarak; en fazla 24 saat sonrası.

Diğer alanlar atılır. identify, widget yüklenmeden önce gelebilir; kuyruğa alınır, erken yüklemeyi tetiklemez. Değerler bağlantı kurulurken iletilir; widget zaten bağlıysa hemen iletilir.

Gizli anahtar

Hesabınızda Proje → Kimlik doğrulama altında projenin gizli anahtarını oluşturursunuz (yetki: projeyi düzenleme). 64 onaltılık karakterden oluşur; tam hâli yalnızca bir kez, sonrasında maskeli gösterilir. Sunucunuzun ortamına koyun; tarayıcı betiğine, uygulamaya veya kod deposuna asla koymayın.

Hesaplama için önemli: HMAC anahtarı, gösterildiği biçimde 64 karakterlik dizenin kendisidir; bundan çözümlenen baytlar değildir.

İmzayı hesaplama

userHash = hex( HMAC_SHA256( secret, userId + "." + exp ) )

Küçük harfli onaltılık, 64 karakter. Doğrulanmış e-posta adresiyle:

userHash = hex( HMAC_SHA256( secret, userId + "." + exp + "." + email ) )

E-posta adresi yalnızca ikinci biçimde doğrulanmış sayılır. exp gerektirir.

PHP:

<?php
$geheim   = getenv('RC_IDENT_SECRET');      // 64 hex characters from the account
$userId   = (string) $kunde->id;
$exp      = time() + 3600;                  // at most 24 h
$userHash = hash_hmac('sha256', $userId . '.' . $exp, $geheim);
?>
<script nonce="<?= $cspNonce ?>">
  ReactiveChat('identify', {
    userId: <?= json_encode($userId) ?>,
    userHash: <?= json_encode($userHash) ?>,
    exp: <?= (int) $exp ?>
  });
</script>

Node.js:

const crypto = require('crypto');

function rcIdentitaet(kunde) {
  const userId = String(kunde.id);
  const exp = Math.floor(Date.now() / 1000) + 3600;
  const userHash = crypto.createHmac('sha256', process.env.RC_IDENT_SECRET)
    .update(userId + '.' + exp)
    .digest('hex');
  return { userId, userHash, exp };
}

Python:

import hmac, hashlib, os, time

def rc_identitaet(kunde_id: str) -> dict:
    exp = int(time.time()) + 3600
    msg = f"{kunde_id}.{exp}".encode()
    key = os.environ["RC_IDENT_SECRET"].encode()   # the hex string as text
    return {"userId": kunde_id, "exp": exp,
            "userHash": hmac.new(key, msg, hashlib.sha256).hexdigest()}

E-posta adresiyle (PHP):

$userHash = hash_hmac('sha256', $userId . '.' . $exp . '.' . $email, $geheim);

Adres tam olarak identify çağrısına ilettiğiniz biçimde imzalanmalıdır.

Satır içi betik olmadan (sıkı CSP)

Content Security Policy satır içi betiklere izin vermiyorsa değerleri veri olarak verip kendi betik dosyanızdan identify çağırın:

<meta name="rc-ident" content='{"userId":"4711","userHash":"9c1f…","exp":1792503600}'>

// /js/chat-ident.js
var m = document.querySelector('meta[name="rc-ident"]');
if (m) { ReactiveChat('identify', JSON.parse(m.content)); }

Tek sayfalı uygulamalarda, oturum açtıktan sonra üç değeri sunucunuzdan fetch ile alın.

Sunucunun kontrol ettikleri

• exp tam sayıdır (Unix saniyesi), gelecektedir ve en fazla 24 saat ileridedir (artı 5 dakika tolerans).
• Özet userId + "." + exp ile (veya e-postalı biçimle) eşleşir. Özette büyük harflere tolerans gösterilir.
• Karşılaştırma sabit sürelidir.

Geçerli özeti ve exp değeri olan kullanıcı doğrulanmış ve güncel sayılır. Yalnızca o zaman müşteri verilerine ve müşteri portalına erişir.

exp içermeyen eski biçim: userHash = HMAC_SHA256(secret, userId) hâlâ doğrulanmış olarak kabul edilir, ancak güncel sayılmaz; sohbet geçmişi ve panelde gösterim için yeterlidir, müşteri verileri için değildir. Mevcut entegrasyonları exp içeren biçime geçirin.

Kontrol başarısız olduğunda

Sohbet çalışmaya devam eder, ancak anonim olarak. Widget auth_failed hatasını, detail.reason içinde nedenle alır:

• no_hash – userHash eksik.
• no_secret – proje için gizli anahtar ayarlanmamış.
• bad_exp – exp saniye cinsinden geçerli tam sayı değil (sık neden: milisaniye iletilmesi).
• expired – exp geçmişte (sayfa uzun süredir açık, sunucu saati yanlış).
• exp_too_far – exp 24 saatten fazla ileride.
• bad_hash – özet eşleşmiyor: yanlış gizli anahtar, yanlış sıra, dize yerine sayı olarak imzalanmış userId, farklı yazılmış e-posta.

Geliştirici araçlarının ağ sekmesinde neden, WebSocket bağlantısının error çerçevesindedir; init_ok.identity, verified ve reason gösterir.

“Yalnızca doğrulanmış ziyaretçilere izin ver” ayarı yoktur; doğrulanmamış ziyaretçiler her zaman anonim olarak sohbet eder.

Gizli anahtarı yenileme

• Yeni gizli anahtar oluştur: Önceki anahtar 24 saat daha geçerli kalır. Bu süre içinde yenisini sunucularınıza girin.
• Kaldır: İkisini de hemen geçersiz kılar. Yeni gizli anahtar ayarlanana kadar tüm kullanıcılar doğrulanmamış sayılır.

Kullanıcı değiştirme ve oturumu kapatma

• identify çağrısını farklı kullanıcıyla yaparsanız (örneğin SPA içinde hesap değiştirdikten sonra) widget giriş taslağını önceki kullanıcıdan ayırır.
• Özel oturum kapatma komutu yoktur. Kimlik yalnızca geçerli sayfa görüntülemesi için uygulanır; oturum kapatıldıktan sonra sayfaları identify olmadan sunun. Sohbet ve ziyaretçi kimliği tarayıcıda tutulur; paylaşılan cihazda artık hiçbir şey görünmemesi gerekiyorsa ziyaretçi widget içinde verilerini silebilir.

Bağlam iletme

Kimliğin yanında sayfanız asistana ve ekibinize şu anda neler olduğunu bildirebilir; örneğin gösterilen ürün veya sepet içeriği. Bu track ile çalışır:

ReactiveChat('track', 'warenkorb', {
  page_type: 'cart',
  cart_value: 129.80,
  cart_items: 3,
  currency: 'EUR'
});

Yalnızca şu alanlar alınır; diğer her şey atılır:

• Sayfa: url, path, title, referrer, page_type, landing_path
• Ürün: product_id, variant_id, category, price, currency, in_stock
• Sepet: cart_value, cart_items
• Kampanya: utm_source, utm_medium, utm_campaign, gclid, msclkid, fbclid
• Sinyaller: intent, intent_confidence, rage_score, scroll_pct, dwell_ms

Widget adresi, başlığı, yönlendireni ve kampanya parametrelerini zaten her sayfa değişikliğinde kendisi kaydeder. Bağlam yalnızca onayla iletilir (Gizlilik entegrasyonu). Bu alanlara kişisel veri yazmayın; bunun için identify vardır.

Mobil uygulamalar

Uygulamada kimliği WebView yüklendikten sonra JavaScript ile iletirsiniz; asla adres üzerinden değil. Burada da özet uygulamada değil, sunucunuzda hesaplanır: Mobil uygulamalar.

Sonraki: Müşteri verisi uç noktası · SPA ve sayfa değişiklikleri