Pengenalpastian Pengguna

Mengenal pasti pengguna menghubungkan sesi sembang tanpa nama dengan profil pengguna sebenar.

Cara ia berfungsi

Apabila anda memanggil Respondo.identify(), medan yang dihantar akan dilampirkan pada perbualan. Semua medan tidak wajib — hantar hanya yang anda ada. Contohnya, anda boleh menghantar userId sahaja tanpa email atau nama. Kakitangan sokongan melihat data ini dalam panel butiran perbualan.

Parameter#

Sifat	Jenis	Wajib	Penerangan
email	string	tidak wajib	Alamat email pengguna
name	string	tidak wajib	Nama paparan
userId	string	tidak wajib	ID pengguna dalaman atau ID paparan anda — ditunjukkan seadanya dalam papan pemuka
userHash	string	tidak wajib	Tandatangan HMAC-SHA256 untuk pengesahan identiti
metadata	object	tidak wajib	Pasangan kunci-nilai bagi medan tersuai (plan, company dan lain-lain)
properties	object	tidak wajib	Sifat kenalan tersuai yang ditakrifkan dalam Agent Settings. Kunci mesti sepadan dengan takrifan sifat. Nilai disimpan dengan awalan `cp_` dan boleh ditapis dalam Peti Masuk.

Contoh: aplikasi satu halaman (SPA)javascript

// Selepas log masuk berjaya
async function onLogin(user) {
  await authenticateUser(user);

  Respondo.identify({
    email: user.email,
    name: user.fullName,
    userId: user.id,
    metadata: {
      plan: user.subscription.plan,
      company: user.company.name,
      role: user.role,
      signedUp: user.createdAt
    },
    properties: {                        // sifat kenalan tersuai
      account_type: user.accountType,    // mesti sepadan dengan kunci dari Agent Settings
      industry: user.industry,
      contract_tier: user.tier
    }
  });
}

Dengan coretan pemasangan standard, anda boleh memanggil identify() pada bila-bila masa — panggilan yang dibuat sebelum widget.js selesai dimuatkan akan dibariskan oleh coretan itu dan dimainkan semula secara automatik sebaik sahaja widget dimulakan. Data identiti hanya dibuang (dengan amaran konsol) jika anda memuatkan widget.js sendiri dan memanggil identify() sebelum pernah memanggil init() — dalam persediaan manual, sentiasa panggil init() dahulu.

Pelawat Tanpa Nama#

Jika anda tidak memanggil identify(), widget secara automatik memberikan ID pelawat kekal yang disimpan dalam localStorage (kunci respondoai_visitor_id). Dalam papan pemuka, perbualan itu dipaparkan sebagai Guest · Web widget.

Mod	Paparan papan pemuka	HMAC diperlukan
Tanpa `identify()`	Guest · Web widget	Tidak
`identify({ email, name })`	Nama + email dipaparkan	Tidak — kecuali Identity Verification diaktifkan; ketika itu email/nama tanpa tandatangan dibuang secara senyap dan sesi kekal tanpa nama
`identify({ userId })`	userId dipaparkan seadanya	Tidak — kecuali Identity Verification diaktifkan; ketika itu `userHash` yang sah diperlukan, jika tidak identiti akan dibuang
`identify({ userId, userHash })`	Identiti pengguna disahkan	Ya — disahkan secara kriptografi

Apabila Identity Verification diaktifkan untuk saluran itu, sebarang identify() yang membawa email atau userId tanpa userHash yang sah akan dibuang di sisi pelayan dan pelawat kekal tanpa nama — lihat Pengesahan Identiti (HMAC) di bawah.

ID pelawat kekal merentas sesi pada pelayar yang sama. Ia tidak pernah dihantar ke Respondo sebagai identiti yang disahkan — ia hanya digunakan untuk kesinambungan perbualan tanpa nama.

Pengenalpastian dengan userId sahaja (tanpa email atau nama)#

Jika platform anda tidak mempunyai email atau nama pengguna — contohnya, anda hanya ada ID paparan dalaman — anda boleh menghantar userId sahaja. Tiada medan lain diperlukan. Papan pemuka akan menunjukkan userId itu seadanya dalam butiran perbualan.

userId + metadata (tanpa email atau nama)javascript

// Platform anda hanya ada ID paparan — itu sudah memadai
Respondo.identify({
  userId: user.displayId,      // cth. "USR-4821" — dipaparkan dalam papan pemuka
  metadata: {                  // konteks tambahan yang tidak wajib
    plan: 'premium',
    region: 'eu-west'
  }
});
// Email atau nama tidak diperlukan — widget berfungsi dengan userId sahaja

Untuk menghalang pemalsuan userId, gandingkannya dengan userHash (lihat Pengesahan Identiti di bawah). Tanpa HMAC, sesiapa sahaja boleh menghantar sebarang userId dari konsol pelayar.

Google Tag Manager / identify() tertunda#

Apabila membenamkan melalui GTM, data pengguna mungkin belum tersedia semasa halaman dimuatkan. Dua pendekatan:

Pilihan A: localStorageKey (tanpa perlu JS)javascript

// Jika platform anda sudah menulis ID pengguna ke localStorage:
Respondo.init({
  agentId: 'YOUR_AGENT_ID',
  localStorageKey: 'myapp_user_id'  // membaca localStorage.getItem('myapp_user_id') secara automatik
});
// Panggilan identify() tidak diperlukan — widget mengambil userId dengan sendirinya

Pilihan B: identify() tertunda melalui dataLayerjavascript

// 1. Mulakan widget serta-merta (tag GTM)
Respondo.init({ agentId: 'YOUR_AGENT_ID' });

// 2. Kemudian, apabila data pengguna muncul (cth. daripada dataLayer atau aplikasi anda):
var waitForUser = setInterval(function() {
  var uid = localStorage.getItem('myapp_user_id');
  if (uid && window.Respondo && typeof window.Respondo.identify === 'function') {
    clearInterval(waitForUser);
    Respondo.identify({ userId: uid });
  }
}, 500);

localStorageKey hanya digunakan jika userId belum ditetapkan melalui identify(). Panggilan identify() yang eksplisit sentiasa diutamakan.

Pengesahan Identiti (HMAC)#

Tanpa pengesahan, sesiapa sahaja boleh menyamar sebagai pengguna dengan menghantar userId atau email palsu. Pengesahan Identiti menggunakan HMAC-SHA256 untuk membuktikan secara kriptografi bahawa identiti pengguna ditetapkan oleh pelayan anda, bukan oleh kod di sebelah klien.

Cara ia berfungsi#

Dayakan Identity Verification dalam tetapan saluran anda — anda akan menerima kunci rahsia.
Pada pelayan anda, kira HMAC-SHA256(secret, userId) — secret ialah kuncinya, userId ialah mesejnya — dan hantar hasilnya ke frontend. Jika anda mengenal pasti pengguna dengan email sahaja (tanpa userId), tandatangani email itu: payload yang ditandatangani ialah userId apabila ada, jika tidak email. Jika anda menghantar kedua-duanya, tandatangani userId; ia diutamakan.
Hantar hash itu sebagai userHash dalam Respondo.identify().
Respondo mengesahkan hash itu di sebelah pelayan. Jika tidak sah, identiti dibuang dan pengguna dianggap tanpa nama.

Jangan sekali-kali dedahkan kunci rahsia anda dalam kod frontend. HMAC mesti dikira pada backend anda.

Setelah pengesahan diaktifkan, setiap identify() yang membawa userId atau email mesti menyertakan userHash yang sah — jika tidak, medan identiti dibuang dan pelawat dianggap tanpa nama.

Contoh di sebelah pelayan#

Node.jsjavascript

const crypto = require('crypto');

const SECRET = process.env.RESPONDO_IDENTITY_SECRET;

function generateUserHash(userId) {
  return crypto
    .createHmac('sha256', SECRET)
    .update(userId)
    .digest('hex');
}

// Dalam endpoint API anda:
app.get('/api/respondo-hash', (req, res) => {
  const hash = generateUserHash(req.user.id);
  res.json({ userHash: hash });
});

Pythonpython

import hmac, hashlib, os

SECRET = os.environ['RESPONDO_IDENTITY_SECRET']

def generate_user_hash(user_id: str) -> str:
    return hmac.new(
        SECRET.encode(),
        user_id.encode(),
        hashlib.sha256
    ).hexdigest()

# Dalam view / endpoint anda:
user_hash = generate_user_hash(request.user.id)

Gogo

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

func GenerateUserHash(userID, secret string) string {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(userID))
    return hex.EncodeToString(mac.Sum(nil))
}

Penggunaan di frontend#

Dengan pengesahan identitijavascript

// Ambil hash daripada pelayan ANDA
const { userHash } = await fetch('/api/respondo-hash').then(r => r.json());

Respondo.identify({
  email: user.email,
  name: user.name,
  userId: user.id,
  userHash: userHash  // tandatangan HMAC-SHA256
});