Kimlik doğrulama

Neden doğrulanır#

Varsayılan olarak SDK anonimdir: kararlı bir visitor_id oluşturur ve onu platformun anahtar deposunda (keystore) tutar. Bu, tek bir cihazda tek bir konuşma için yeterlidir. Belirli bir kullanıcıyı tanımak, yeniden oturum açmada veya başka bir cihazda geçmişi geri yüklemek ve bir konuşmayı güvenilir biçimde bir kişi profiline bağlamak için, backend’in istemcinin iddia ettiği kişi olduğuna dair kanıta ihtiyacı vardır. SDK sadece “ben kullanıcı 42’yim” diye gönderseydi, herkes başka bir kimliği taklit edip başkasının sohbetini okuyabilirdi — bu yüzden Respondo, yalnızca backend’inizin üretebileceği kriptografik bir imza olan userHash’i ister.

Identity secret’ı edinme#

identity_secret, ajanınıza (widget kanalınızın bağlı olduğu yapay zeka ajanı) bağlı gizli bir dizedir. Panelde şu yoldan oluşturun: Kanallar → Widget → Kimlik doğrulama. Gizli anahtar ajanda durduğu için, o ajana bağlı her kanal — web widget’ı ve mobil SDK — aynı gizli anahtarı paylaşır. Kimlikleri imzalama hakkını verir; bu yüzden yalnızca backend’inizde bulunmalı ve asla uygulamayla gönderilmemelidir.

userHash formülü#

userHash, küçük harfli hex olarak kodlanmış, tek bir imzalanmış kimlik dizesi üzerinden bir HMAC-SHA256’dır:

userHash = HMAC_SHA256( identity_secret, payload )

payload = userId          // userId ayarlıysa
        = email           // aksi halde, email ayarlıysa
        = (geçersiz)      // ikisi de boşsa, imzalanacak bir şey yoktur

• Gizli anahtar HMAC anahtarıdır; kimlik dizesi ise mesajdır — tersi değil.
• Tam olarak tek bir dizeyi imzalayın — ham userId (veya e-posta), salt ya da JSON sarmalayıcısı olmadan.
• Hem userId hem e-posta geçirirseniz, userId’yi imzalayın (önceliklidir).
• Çıktı hex’tir (SHA-256 için 64 karakter), base64 değil.

Backend örnekleri#

İmzayı backend’inizde hesaplayın ve tamamlanmış userHash’i uygulamaya verin.

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

// HMAC_SHA256(identity_secret, userId), küçük harfli hex olarak.
func ComputeUserHash(identitySecret, userID string) string {
    mac := hmac.New(sha256.New, []byte(identitySecret))
    mac.Write([]byte(userID))
    return hex.EncodeToString(mac.Sum(nil))
}

const crypto = require("crypto");

// Mobil istemcide Respondo.identify'a geçirilecek userHash'i döndürür.
function computeUserHash(identitySecret, userId) {
  return crypto
    .createHmac("sha256", identitySecret)
    .update(userId, "utf8")
    .digest("hex");
}

import hmac
import hashlib

# Mobil istemcide Respondo.identify'a geçirilecek userHash'i döndürür.
def compute_user_hash(identity_secret: str, user_id: str) -> str:
    return hmac.new(
        identity_secret.encode(),
        user_id.encode(),
        hashlib.sha256,
    ).hexdigest()

<?php
// Mobil istemcide Respondo.identify'a geçirilecek userHash'i döndürür.
function computeUserHash(string $identitySecret, string $userId): string {
    return hash_hmac('sha256', $userId, $identitySecret);
}

Hash Respondo’ya nasıl ulaşır#

İki durak var ve yalnızca ilkini siz kuruyorsunuz:

1. Backend’iniz → uygulamanız. Hash’i istediğiniz gibi iletirsiniz. En ucuz seçenek, zaten döndürdüğünüz oturum açma/bootstrap yanıtına fazladan bir alan eklemektir — ek bir gidiş dönüş olmaz. Kendi backend’inizde ayrı bir uç nokta (örneğin POST /myapp/identity → { userId, userHash }) de aynı ölçüde işe yarar. Respondo bu uç noktayı barındırmaz — onu siz yazarsınız.
2. Uygulamanız → Respondo. Bunu SDK halleder. identify çağrısını yaptığınız anda SDK hash’i ilgili her isteğe ekler ve backend her seferinde yeniden doğrular.

POST /api/v1/chat                      body   identity.userHash
GET  /api/v1/chat/resume               query  user_hash
GET  /api/v1/chat/history              query  user_hash
GET  /api/v1/chat/ws                   frames    user_hash (bağlantıdan sonra subscribe/identify JSON çerçeveleri — handshake URL'inde değil)
GET  /api/v1/widget/tours              query  user_hash
GET  /api/v1/widget/checklists         query  user_hash
POST /api/v1/widget/push/register      body   user_hash

Hash bir oturum için bir kez takas edilmez, her istekte yeniden denetlenir — çalınmış bir userId’yi tek başına işe yaramaz kılan da budur.

Kimliği SDK’ya geçirme#

İmzalanmış kimliği backend’inizden alın, ardından userHash’i herhangi bir platformda identify’a geçirin:

Respondo.identify(
    RespondoIdentity(userId = "42", email = "user@example.com", userHash = hash),
)

Respondo.identify(
    RespondoIdentity(userId: "42", email: "user@example.com", userHash: hash)
)

Respondo.identify(RespondoIdentity(
  userId: '42', email: 'user@example.com', userHash: hash,
));

Geçersiz userHash davranışı#

Doğrulama ajanda etkinken ve imza eksik ya da yanlış olduğunda, backend sessiz bir anonim düşürme gerçekleştirir: sohbet yine çalışır, visitor_id korunur ve konuşma anonim kişiye bağlanır — ancak profile bağlantı ve cihazlar arası geçmiş yoktur. Bir kullanıcı “tanınmıyorsa”, neredeyse her zaman sebep imzadır: userId’yi imzaladığınızı (e-posta ya da JSON değil), doğru identity_secret’ı kullandığınızı ve küçük harfli hex ürettiğinizi kontrol edin. Temsilcinin identity_secret’ı boşsa, doğrulama kapalıdır ve userId / e-posta olduğu gibi kabul edilir.

identity_secret’ı döndürmek fiilen sert bir geçiştir: eski gizli anahtarla üretilmiş her hash bir anda doğrulanmayı bırakır; böylece halihazırda oturum açmış kullanıcılar, backend’iniz onların userHash’ini yeni gizli anahtarla yeniden hesaplayıp yeniden sağlayana kadar sessizce anonime geri düşer. Gizli anahtarı yalnızca imzalayan tarafı aynı pencerede güncelleyebildiğinizde döndürün.