Azonosítsd a bejelentkezett felhasználóidat egyedi adatokkal

Alapértelmezés szerint a Yaplet minden böngésző-munkamenetet névtelen látogatóként kezel. Ez azt jelenti, hogy a csapatod „Látogató 1234”-et lát valódi név helyett, és ugyanaz az ügyfél minden bejelentkezéskor új beszélgetést kezd. Ha egyszer meghívod a Yaplet.identify()-t munkamenetenként, ez megoldódik: a widget megjeleníti a felhasználó nevét, összekapcsolja az összes korábbi beszélgetését, és lehetővé teszi az inbox szűrését csomag, vállalat vagy bármilyen egyedi tulajdonság alapján.

Előfeltételek

• A Yaplet kódrészlet már telepítve van. Ha még nem, kezdd itt: A Yaplet telepítése JavaScript-kódrészlettel.
• Van egy szerveroldali munkamenet, amely ismeri az aktuális felhasználó azonosítóját és e-mail-címét.
• Tudsz néhány sor kódot futtatni a szervereden – a felhasználó azonosításához olyan aláírás kell, amelyet csak ott lehet előállítani.

1. Írd alá a felhasználó azonosítóját a szervereden

Bárki megnyithatja a weboldaladat és írhat a chat-widgetnek, ezért a felhasználói azonosító önmagában csak egy állítás – bizonyíték nélkül egy idegen is beküldhetné az egyik ügyfeled azonosítóját, és a csapatod őt látná annak az ügyfélnek. Ezt megakadályozandó minden identify() hívásnak tartalmaznia kell egy aláírást, amelyet csak a szervered tud előállítani. Az érvényes aláírás nélküli hívásokat elutasítjuk, és a látogató névtelen marad.

Az azonosítási kulcsodat a Yaplet vezérlőpultjában találod: Márka → (a márkád) → Chat widget → Telepítés → Személyazonosság ellenőrzése. Tárold környezeti változóként a szervereden.

A kulcs rejtve marad, amíg rá nem nyomsz a Titkos kulcs megjelenítése gombra, és van mellette másolás gomb is. Van egy Kulcs cseréje művelet is, megerősítés mögött — akkor használd, ha a kulcs kiszivárgott, de tudd, mit tesz: a régi kulcs a megerősítés pillanatában érvénytelenné válik, és minden identify() hívás sikertelen lesz, amíg a szervereden nem élesíted az újat.

Ezután készítsd el belőle a felhasználó azonosítójának hashét. Node.js-ben:

import crypto from "crypto";

const userHash = crypto
  .createHmac("sha256", process.env.YAPLET_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");

A userHash értéket küldd el a frontendednek a felhasználó adataival együtt – például egy újabb mezőként azon a „bejelentkezett felhasználó” végponton, amelyet már úgyis meghívsz.

Soha ne tedd az azonosítási kulcsot a weboldalad kódjába. Amit a böngésző le tud tölteni, azt a látogató el is tudja olvasni – és akinél a kulcs van, az bármelyik felhasználód nevében felléphet. A kulcsnak kizárólag a szervereden a helye.

2. Hívd meg az identify() függvényt

Hívd meg a Yaplet.identify()-t az oldal betöltése után, amikor a felhasználói munkamenet már elérhető. Első argumentumként add meg a felhasználó egyedi azonosítóját, másodikként az adatait tartalmazó objektumot, harmadikként pedig az 1. lépésben készített aláírást:

Yaplet.identify("user-123", {
  name: "Kiss Éva",
  email: "[email protected]",
  phone: "+36 30 123 4567",
  createdAt: new Date("2024-03-15"),
  plan: "pro",
  companyId: "pelda-001",
  companyName: "Példa Kft.",
}, userHash);

A felhasználó azonosítója és az aláírás egyaránt kötelező, és az átadott azonosítónak pontosan azzal a szöveggel kell egyeznie, amelyből a szerveren a hash készült. A középső objektumban minden mező opcionális – de minél több adatot küldesz, annál több kontextust kap a csapatod egy-egy beérkező beszélgetésnél.

Szabványos mezők

Mező	Típus	Leírás
name	string	Teljes név, amely az inboxban és a látogatói profilon jelenik meg.
email	string	Kapcsolattartási e-mail-cím. Lehetővé teszi az e-mailes utókövetést a chat után.
phone	string	Telefonszám E.164 formátumban (pl. +36301234567).
value	number	Élettartam-érték a te valutádban. A látogatói oldalsávon jelenik meg.
companyId	string	Belső vállalatazonosító B2B szűréshez.
companyName	string	Vállalat megjelenített neve.
plan	string	Előfizetési csomag neve (pl. "free", "pro", "enterprise").
sla	number	Cél válaszidő órában ennél a felhasználónál. Kiemeli az SLA-érzékeny beszélgetéseket.
createdAt	Date	A felhasználó regisztrációjának dátuma. Kohorsz-alapú támogatási szabályokhoz hasznos.

Egyedi attribútumok

Minden adat, amely nem fér bele a szabványos mezőkbe, a customData-ba kerülhet. Ezek szabad formátumú kulcs-érték párok:

Yaplet.identify("user-123", {
  name: "Kiss Éva",
  email: "[email protected]",
  customData: {
    subscriptionStatus: "trialing",
    trialEndsAt: "2026-06-15",
    accountRegion: "EU",
    featureFlags: "ai-phone,affiliate",
  },
}, userHash);

Az egyedi attribútumok megjelennek a látogatói oldalsávon az inboxban, és a csapatod szűrhet is rájuk.

Az AI-hoz is eljutnak. Amit a customData-ban átadsz, az custom_<kulcs> néven elérhetővé válik az API eszközeidnek, így az AI válaszadás közben átadhatja a látogató saját fiókadatait a rendszereidnek. A korlátok: az első 50 kulcsot használjuk fel, minden értéket 512 karakternél levágunk, a beágyazott objektumokat és listákat pedig kihagyjuk, mert nincs értelmes egysoros alakjuk egy webcímben vagy egy fejlécben.

Hol hívd meg az identify()-t?

Hívd meg azonnal, amint az alkalmazásod tudja, ki az aktuális felhasználó – jellemzően az autentikáció ellenőrzése után. Egyoldalas alkalmazásokban általában a gyökérkomponensben vagy az auth store-ban a legjobb hely. Szerveroldali renderelés esetén inline is elhelyezheted az oldal válaszában.

A Yaplet.identify()-t bármikor meghívhatod a kódrészlet futása után – akár az SDK teljes betöltése előtt is. A kódrészlet sorba állítja a hívást, és az SDK betöltése után végrehajtja.

Kijelentkezés

Amikor egy felhasználó kijelentkezik az alkalmazásodból, töröld a Yaplet azonosítást, hogy a következő látogató ne örökölje a beszélgetési előzményeit:

Yaplet.clearIdentity();

Hibakeresés

Ha a felhasználóid továbbra is névtelen látogatóként jelennek meg, nézd át sorban ezt a négy okot. Érdemes a böngésző konzolját is megnyitni, és megnézni, van-e Yaplet-figyelmeztetés az identify() hívásról – ha kiírunk ilyet, az tartalmazza a szerver saját indoklását is.

• Nem küldtél aláírást. Hiányzik a harmadik argumentum, vagy a szervered üres értéket adott vissza.
• Az aláírás nem illik az azonosítóhoz. A szervered mást hashelt, mint amit a böngésző átadott – például az egyik oldalon szám, a másikon szöveg szerepel, e-mail-cím került azonosító helyett, vagy felesleges szóköz maradt benne.
• Rossz kulcsot használtál. Az azonosítási kulcs ehhez a widgethez tartozik, tehát egy máshonnan átmásolt kulcs sosem fog egyezni.
• Lecserélted a kulcsot, de a szervered még a régit használja.

Mi a következő lépés?

Ha az azonosítás be van állítva, a csapatod már akkor tudja, kivel beszél, amikor egy új beszélgetés érkezik. Ellenőrizd, hogy minden rendben működik-e: Telepítés ellenőrzése.