Pagpapatunay ng identity

Bakit kailangang patunayan#

Bilang default, anonymous ang SDK: bumubuo ito ng matatag na visitor_id at itinatago ito sa keystore ng plataporma. Sapat na iyon para sa isang usapan sa isang device. Para makilala ang isang partikular na user, maibalik ang kasaysayan sa muling pag-log in o sa ibang device, at maiugnay nang maaasahan ang usapan sa profile ng contact, kailangan ng backend ng patunay na siya nga ang sinasabi ng kliyente. Kung basta na lang magpapadala ang SDK ng "ako si user 42", kahit sino ay makakapagpanggap na ibang id at makakabasa ng chat ng iba — kaya humihingi ang Respondo ng cryptographic na lagda, userHash, na ang backend lamang ninyo ang makakagawa.

Pagkuha ng identity secret#

Ang identity_secret ay lihim na string na nakatali sa ahente ninyo (ang manggagawang AI na kinakabitan ng widget channel ninyo). Buuin ito sa dashboard sa ilalim ng Mga Channel → Widget → Pagpapatunay ng identity. Dahil nasa ahente ito, iisang secret ang ginagamit ng bawat channel na pinapatakbo ng ahenteng iyon — pareho ang web widget at ang mobile SDK. Nagbibigay ito ng karapatang lagdaan ang mga identity, kaya dapat itong manatili lamang sa backend ninyo at hindi kailanman ipadala kasama ng app.

Pormula ng userHash#

Ang userHash ay HMAC-SHA256 sa iisang nilagdaang string ng identity, naka-encode bilang lowercase hex:

userHash = HMAC_SHA256( identity_secret, payload )

payload = userId          // kung nakatakda ang userId
        = email           // kung hindi, kung nakatakda ang email
        = (invalid)       // kung pareho silang walang laman, walang ilalagda

• Ang secret ang susi ng HMAC; ang string ng identity ang mensahe — hindi kabaligtaran.
• Lagdaan ang eksaktong isang string — ang hilaw na userId (o ang email), na walang salt o JSON wrapper.
• Kung ipapasa ninyo nang sabay ang userId at ang email, ang userId ang lagdaan (ito ang may prayoridad).
• Hex ang output (64 na karakter para sa SHA-256), hindi base64.

Mga halimbawa sa backend#

Kalkulahin ang lagda sa backend ninyo at ibigay ang tapos nang userHash sa app.

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

// HMAC_SHA256(identity_secret, userId) bilang lowercase hex.
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");

// Ibinabalik ang userHash na ipapasa sa Respondo.identify sa mobile client.
function computeUserHash(identitySecret, userId) {
  return crypto
    .createHmac("sha256", identitySecret)
    .update(userId, "utf8")
    .digest("hex");
}

import hmac
import hashlib

# Ibinabalik ang userHash na ipapasa sa Respondo.identify sa mobile client.
def compute_user_hash(identity_secret: str, user_id: str) -> str:
    return hmac.new(
        identity_secret.encode(),
        user_id.encode(),
        hashlib.sha256,
    ).hexdigest()

<?php
// Ibinabalik ang userHash na ipapasa sa Respondo.identify sa mobile client.
function computeUserHash(string $identitySecret, string $userId): string {
    return hash_hmac('sha256', $userId, $identitySecret);
}

Paano nakakarating ang hash sa Respondo#

Dalawang hakbang, at ang una lang ang inyong itatayo:

1. Backend ninyo → app ninyo. Kayo ang bahalang maghatid ng hash. Ang pinakamurang opsyon ay dagdag na field sa tugon ng login/bootstrap na ibinabalik ninyo — walang karagdagang round trip. Gumagana rin nang pantay ang nakalaang endpoint sa sarili ninyong backend (halimbawa, POST /myapp/identity na nagbabalik ng { userId, userHash }). Hindi hino-host ng Respondo ang endpoint na iyon — kayo ang gumagawa nito.
2. App ninyo → Respondo. Inaasikaso na ito para sa inyo. Kapag tinawag ninyo ang identify, ikinakabit ng SDK ang hash sa bawat kaugnay na request at muling pinapatunayan ito ng backend sa tuwing dumarating.

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

Muling sinusuri ang hash sa bawat request — hindi ito ipinagpapalit nang minsanan para sa isang session, at iyan ang dahilan kung bakit walang silbi ang ninakaw na userId nang mag-isa.

Pagpasa ng identity sa SDK#

Kunin ang nilagdaang identity mula sa backend ninyo, pagkatapos ay ipasa ang userHash sa identify sa alinmang plataporma:

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

Kilos kapag mali ang userHash#

Kapag naka-on ang pagpapatunay sa ahente at nawawala o mali ang lagda, nagsasagawa ang backend ng tahimik na pagbaba tungo sa anonymous: patuloy pa ring gumagana ang chat, nananatili ang visitor_id, at naikakabit ang usapan sa anonymous na contact — ngunit walang ugnayan sa profile at walang kasaysayan sa iba't ibang device. Kung "hindi nakikilala" ang isang user, halos palaging ang lagda ang dahilan: tiyaking nilagdaan ninyo ang userId (hindi ang email o JSON), ginamit ninyo ang tamang identity_secret, at lowercase hex ang inilabas ninyo. Kung walang laman ang identity_secret ng ahente, naka-off ang pagpapatunay at tinatanggap ang userId / email nang ganoon na lang.

Ang pagpapalit ng identity_secret ay isang matigas na paglipat: agad na hihinto sa pagpasa ng pagsusuri ang bawat hash na ginawa gamit ang lumang secret, kaya tahimik na babalik sa anonymous ang mga naka-log in nang user hanggang muling kalkulahin at muling ibigay ng backend ninyo ang userHash nila gamit ang bagong secret. Palitan lang ang secret kapag kaya ninyong i-update ang panig na lumalagda sa loob ng parehong yugto.