Pengesahan identiti

Mengapa perlu disahkan#

Secara lalai SDK ini beroperasi tanpa nama: ia menjana visitor_id yang stabil dan menyimpannya dalam keystore platform. Itu memadai untuk satu perbualan pada satu peranti. Untuk mengenali pengguna tertentu, memulihkan sejarah apabila log masuk semula atau pada peranti lain, dan mengikat perbualan kepada profil kenalan dengan pasti, backend memerlukan bukti bahawa klien itu benar-benar orang yang didakwanya. Jika SDK hanya menghantar "saya pengguna 42", sesiapa sahaja boleh memalsukan id orang lain dan membaca sembang orang tersebut — sebab itu Respondo memerlukan tandatangan kriptografi, userHash, yang hanya boleh dihasilkan oleh backend anda.

Mendapatkan identity secret#

identity_secret ialah rentetan rahsia yang terikat kepada ejen anda (pekerja AI yang disambungkan kepada saluran widget anda). Jana ia dalam papan pemuka di bawah Channels → Widget → Identity verification. Oleh sebab ia berada pada ejen, setiap saluran yang disokong ejen tersebut — widget web mahupun SDK mudah alih — berkongsi rahsia yang sama. Ia memberikan hak untuk menandatangani identiti, jadi ia mesti berada hanya pada backend anda dan tidak boleh sekali-kali dihantar bersama aplikasi.

Formula userHash#

userHash ialah HMAC-SHA256 ke atas satu rentetan identiti yang ditandatangani, dikodkan sebagai hex huruf kecil:

userHash = HMAC_SHA256( identity_secret, payload )

payload = userId          // jika userId ditetapkan
        = email           // jika tidak, dan email ditetapkan
        = (invalid)       // jika kedua-duanya kosong, tiada apa untuk ditandatangani

• Rahsia itu ialah kunci HMAC; rentetan identiti pula ialah mesej — bukan sebaliknya.
• Tandatangani tepat satu rentetan — userId mentah (atau e-mel), tanpa salt atau pembalut JSON.
• Jika anda menghantar kedua-dua userId dan e-mel, tandatangani userId (ia diutamakan).
• Outputnya ialah hex (64 aksara untuk SHA-256), bukan base64.

Contoh untuk backend#

Kira tandatangan itu pada backend anda dan serahkan userHash yang siap kepada aplikasi.

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

// HMAC_SHA256(identity_secret, userId) sebagai hex huruf kecil.
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");

// Memulangkan userHash untuk dihantar ke Respondo.identify pada klien mudah alih.
function computeUserHash(identitySecret, userId) {
  return crypto
    .createHmac("sha256", identitySecret)
    .update(userId, "utf8")
    .digest("hex");
}

import hmac
import hashlib

# Memulangkan userHash untuk dihantar ke Respondo.identify pada klien mudah alih.
def compute_user_hash(identity_secret: str, user_id: str) -> str:
    return hmac.new(
        identity_secret.encode(),
        user_id.encode(),
        hashlib.sha256,
    ).hexdigest()

<?php
// Memulangkan userHash untuk dihantar ke Respondo.identify pada klien mudah alih.
function computeUserHash(string $identitySecret, string $userId): string {
    return hash_hmac('sha256', $userId, $identitySecret);
}

Bagaimana hash sampai ke Respondo#

Dua lompatan, dan hanya yang pertama perlu anda bina:

1. Backend anda → aplikasi anda. Anda menghantar hash itu mengikut cara yang anda suka. Pilihan paling murah ialah medan tambahan pada respons log masuk/bootstrap yang memang anda pulangkan — tiada permintaan tambahan. Endpoint khusus pada backend anda sendiri (contohnya POST /myapp/identity yang memulangkan { userId, userHash }) berfungsi sama baiknya. Respondo tidak menyediakan endpoint itu — anda yang melaksanakannya.
2. Aplikasi anda → Respondo. Ini diuruskan untuk anda. Sebaik sahaja anda memanggil identify, SDK melekatkan hash itu pada setiap permintaan yang berkaitan dan backend mengesahkannya semula setiap kali.

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 (subscribe/identify JSON frames after connect — not in the handshake URL)
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 itu disemak semula pada setiap permintaan, bukan ditukar sekali sahaja untuk satu sesi — itulah yang menjadikan userId yang dicuri tidak berguna dengan sendirinya.

Menghantar identiti ke SDK#

Ambil identiti yang telah ditandatangani daripada backend anda, kemudian hantar userHash ke dalam identify pada mana-mana platform:

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,
));

Kelakuan apabila userHash tidak sah#

Apabila pengesahan dihidupkan pada ejen dan tandatangan tiada atau salah, backend melakukan penurunan senyap kepada status tanpa nama: sembang tetap berfungsi, visitor_id dikekalkan, dan perbualan itu diikat kepada kenalan tanpa nama — tetapi tiada pautan kepada profil dan tiada sejarah merentas peranti. Jika seorang pengguna "tidak dikenali", hampir selalu puncanya ialah tandatangan: semak bahawa anda menandatangani userId (bukan e-mel atau JSON), menggunakan identity_secret yang betul, dan mengeluarkan hex huruf kecil. Jika identity_secret ejen kosong, pengesahan dimatikan dan userId / e-mel diterima seadanya.

Menggilir identity_secret pada dasarnya ialah peralihan serta-merta: setiap hash yang dihasilkan dengan rahsia lama serta-merta gagal disahkan, jadi pengguna yang sudah log masuk akan jatuh semula kepada status tanpa nama secara senyap sehingga backend anda mengira semula dan membekalkan semula userHash mereka dengan rahsia baharu. Tukar rahsia itu hanya apabila anda boleh mengemas kini pihak penandatangan dalam tetingkap masa yang sama.