Személyazonosság ellenőrzése

Miért kell aláírás az identify() híváshoz

A widgetnek olyan oldalakon is működnie kell, ahol senki nincs bejelentkezve, ezért bármelyik böngésző kaphat látogatói munkamenetet egy nyilvános widgethez. Emiatt egy aláírás nélküli felhasználói azonosító csak állítás, nem tény: aláírás nélkül bárki meghívhatná a saját böngészőjéből a Yaplet.identify("user-4821") függvényt, pontosan úgy jelenne meg a beérkezett üzenetek között, mint az adott ügyfél, és az ügyintéző vagy az AI kiadná neki az adatait.

A személyazonosság ellenőrzése ezt zárja le. A szervered aláírja a felhasználói azonosítót egy olyan titkos kulccsal, amit csak te és a Yaplet ismer, a Yaplet pedig ellenőrzi az aláírást, mielőtt bármit ráírna a látogatóra.

A Yaplet.identify() hívást érvényes hash nélkül elutasítjuk. Semmi nem mentődik el — még részleges azonosítás sem —, mert a beérkezett üzeneteket néző ügyintéző nem tudja megkülönböztetni az ellenőrzött látogatót a nem ellenőrzöttől. Ha e nélkül élesíted az identify() hívást, minden bejelentkezett felhasználód névtelen marad.

Hol találod az azonosítási titkos kulcsot

A Yaplet vezérlőpultodon menj a Márka → Chat widget menüpontra, nyisd meg a Telepítés fület, és görgess a beágyazási kódrészlet alatti Személyazonosság ellenőrzése részhez. A Titkos kulcs megjelenítése gombbal töltöd be — csak akkor kérjük le a szerverről, amikor kéred, és akkor is részben elrejtve jelenik meg. Az érték melletti szem ikon fedi fel a teljes kulcsot, a mellette lévő vágólap ikon pedig lemásolja.

Minden chat widgetnek saját titkos kulcsa van, és a megtekintéséhez Brands jogosultság kell.

Tartsd a kulcsot a szervereden — a szokásos hely egy környezeti változó. Soha ne tedd frontend kódba, mobilalkalmazás csomagjába vagy bármi másba, amit egy látogató elolvashat: aki megszerzi, bármelyik felhasználód nevében felléphet.

Beállítás két lépésben

Írd alá a felhasználói azonosítót a szervereden

Számolj HMAC-SHA256 értéket a felhasználó azonosítójából, az azonosítási titkos kulccsal, és add vissza a hexadecimális eredményt a frontendednek a felhasználó profiljával együtt.

import crypto from "crypto";

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

USER_HASH=$(printf '%s' "$USER_ID" | openssl dgst -sha256 -hmac "$YAPLET_IDENTITY_SECRET" | sed 's/^.* //')

<?php
$userHash = hash_hmac(
  'sha256',
  (string) $user->id,
  getenv('YAPLET_IDENTITY_SECRET')
);

import hashlib, hmac, os

user_hash = hmac.new(
    os.environ["YAPLET_IDENTITY_SECRET"].encode(),
    str(user.id).encode(),
    hashlib.sha256,
).hexdigest()

Add át a hasht az identify() hívásnak

A hasht a Yaplet.identify() harmadik paramétereként add át, a felhasználói azonosító és a profil mellett:

JavaScript

Yaplet.identify(
    user.id,
    {
        name: user.name,
        email: user.email,
    },
    userHash,
);

Pontosan ugyanazt a szöveget írd alá, amit első paraméterként átadsz — ha a backended egy számot ír alá, a frontended pedig más formátumú szöveget küld, a hashek nem fognak egyezni. Magánál a hashnél a kis- és nagybetű, valamint a körülötte lévő szóköz nem számít.

Mi történik, ha az ellenőrzés sikertelen

Az elutasított hívás látható, de csak annak, aki a megfelelő helyre néz:

A kérést visszautasítjuk, és semmi nem íródik a látogatói rekordba.
Az SDK hibát ír a böngésző konzoljába, amely a [Yaplet] identify() was rejected szöveggel kezdődik, majd az okot közli.
Az érintett emberek névtelen látogatóként jelennek meg a beérkezett üzenetek között.
A vezérlőpulton nincs figyelmeztetés. Az egyetlen jelzés a böngésző konzolja, ezért integráció közben nézd meg.

Két másik elutasítást is érdemes felismerni. A látogatói tokenedben megnevezett widgetnek ugyanahhoz a szervezethez kell tartoznia, mint a látogatói rekordnak — ha nem így van, a hívást a "Visitor does not belong to this widget" üzenettel utasítjuk el, és éppen ez akadályozza meg, hogy az egyik szervezet widgetjére kiállított token egy másik szervezet látogatójára írjon azonosítást. Ha pedig egyáltalán nem tudjuk kikeresni a látogatót vagy a widgetet, "Could not verify identity right now" választ kapsz; ez nálunk fellépő átmeneti hiba, nem hibás integráció.

Az elutasítási üzenet jelenleg egy régi menüútvonalat nevez meg. Azt írja, hogy a "Widgets → your widget → Embed" alatt keresd, de ez a képernyő már nem létezik. A valódi helye a Márka → Chat widget → Telepítés → Személyazonosság ellenőrzése.

A titkos kulcs cseréje

Miután betöltötted a kulcsot, alatta megjelenik a Kulcs cseréje gomb, megerősítő párbeszédablakkal.

A csere azonnal életbe lép. A régi kulcs a megerősítés pillanatában érvénytelenné válik, és minden identify() hívás sikertelen lesz — a bejelentkezett felhasználóid névtelenként jelennek meg —, amíg az új kulcs ki nem kerül a backendedre. Nincs átfedési időszak, ezért nyugodt időszakban cserélj, és azonnal élesítsd az új értéket.

Cseréld le a kulcsot, ha kiszivárgott: bekerült egy repóba, bemásolták egy hibajegybe, vagy frontend kódban élesítették.

Mi mást vihet még az identify()

A profil objektum többet is átadhat egy névnél és egy e-mail-címnél:

A felismert mezők a látogatóra kerülnek: név, e-mail, telefonszám, csomag és érték. Minden más, amit küldesz, egyedi adatként tárolódik, és megjelenik a beérkezett üzenetek látogatói paneljén.
Az ismételt hívások összefésülnek. Az újabb identify() hívás bővíti a tárolt egyedi adatokat, nem felülírja őket.
Az egyedi attribútumok eljutnak az API eszközeidhez custom_<key> nevű helyőrzőként — legfeljebb 50 darab, egyenként 512 karakterre vágva. A beágyazott objektumokat és listákat kihagyjuk, mert nincs értelmes módjuk egy URL-ben vagy fejlécben szerepelni.
A túl hosszú értékeket levágjuk, nem utasítjuk el, így egy jogos hívás soha nem bukik el pusztán a hosszon.

Még nincs telepítve? A Telepítés útmutató bemutatja a beágyazási kódrészletet, aminek az oldalon kell lennie, mielőtt az identify() bármit tehetne.