Autentizace návštěvníků¶

Ve výchozím stavu považuje chatovací widget každého návštěvníka za anonymního a rozpoznává ho podle prohlížeče. Autentizace návštěvníků to nahradí ověřenou identitou: vaše stránka sdělí, kdo návštěvník je, pomocí tokenu podepsaného vaším identity providerem, a platforma si tento token ověří dřív, než čemukoli v něm uvěří.

Jakmile je návštěvník ověřený, váže se historie konverzací na osobu, nikoli na prohlížeč, a hodnoty z tokenu — číslo smlouvy, zákaznický segment, jméno — se dostanou do dialogu v podobě, kterou návštěvník nemůže změnit.

Kdy ji potřebujete¶

Zapnutí autentizace zvažte, pokud platí cokoli z následujícího:

Je zapnutá historie chatu a zařízení se sdílejí. Anonymní návštěvník je rozpoznáván podle prohlížeče, ne podle osoby, takže na sdíleném počítači se k jeho konverzacím dostane i další uživatel téhož prohlížeče.
Dialog pracuje s osobními údaji. Stav objednávky, faktury, údaje ze smlouvy — cokoli, co má vidět jen ten, komu to patří.
Chcete konverzaci navázat na zákaznický účet. Autentizace přenese do platformy váš vlastní identifikátor zákazníka, takže lze konverzace spárovat se správným záznamem.

Warning

Bez autentizace je historie chatu vázaná na prohlížeč. Kdokoli, kdo prohlížeč použije po návštěvníkovi, se k ní dostane. Tam, kde dialog pracuje s osobními údaji, je právě tohle riziko, kvůli kterému autentizace existuje.

Jak to funguje¶

Vaše stránka podepíše token (JWT) popisující návštěvníka. Token se podepisuje privátním klíčem vašeho identity provideru.
Stránka zavolá window.daktelaAiChat.authorize() s tímto tokenem.
Platforma ověří podpis oproti veřejnému klíči, který jste nastavili, a zkontroluje vydavatele, příjemce a platnost.
Pokud vše sedí, platforma vydá session a konverzace pokračuje pod ověřenou identitou.

Widget nikdy nebere na slovo, co o návštěvníkovi tvrdí stránka. Vše, čemu věří, pochází z tokenu, který si sám ověřil — proto musí privátní klíč zůstat na vašem serveru a nikdy se nesmí dostat do prohlížeče.

Záložka Autentizace s očekávanou strukturou tokenu a popisem, jak se přihlášení volá

Přihlášený návštěvník vidí v hlavičce chatu zámeček:

Hlavička chatu se zámečkem vedle názvu asistenta

Nastavení ověřování¶

Otevřete widget, přejděte na záložku Autentizace a zapněte Povolit ověřování.

Vydavatel a příjemce¶

Pole	Co vyplnit
Vydavatel (issuer)	Musí přesně odpovídat claimu `iss` v tokenu.
Příjemce (audience)	Musí odpovídat claimu `aud`.

Warning

Každému chatovacímu oknu doporučujeme přidělit vlastní hodnotu Příjemce (audience); jinak token vydaný pro jedno okno přihlásí návštěvníka i ve všech ostatních oknech, která důvěřují témuž vydavateli.

Podpisový klíč¶

Podpis musí být asymetrický — token se podepisuje vaším privátním klíčem a platforma drží vždy jen odpovídající veřejný klíč. Symetrické algoritmy jako HS256, kde obě strany sdílejí jedno tajemství, přijímané nejsou. Podporované jsou RS256/384/512, PS256/384/512 a ES256/384/512, přičemž konkrétní algoritmus vybírat nemusíte.

V poli Umístění veřejného klíče zvolte, kde má platforma veřejný klíč hledat:

JWKS URL — adresa vašeho JWKS endpointu. Musí používat HTTPS a být dostupná z internetu. Rotace klíčů pak probíhá automaticky, což z této volby dělá lepší variantu všude, kde takový endpoint nabídnout můžete.
Vložený veřejný klíč — pro případy, kdy veřejný JWKS endpoint neexistuje. Vyplňte ID klíče (kid) a Veřejný klíč (PEM). Rotace klíčů se pak stává ruční změnou v této konfiguraci.

Přes Přidat klíč lze zadat až pět veřejných klíčů. Při rotaci ponechte v seznamu předchozí klíč, dokud nevyprší všechny tokeny jím podepsané.

Claimy s identitou¶

Claim s identifikátorem zákazníka určuje, který claim návštěvníka identifikuje. Výchozí hodnota je sub.

Warning

Použijte claim, který váš identity provider skutečně ověřuje. Odkaz na nepotvrzenou e-mailovou adresu umožní přihlášení pod identitou jiné osoby.

Pole Claim s jménem (nepovinné) a Claim s příjmením (nepovinné) umožní botovi oslovovat návštěvníka jménem. K ničemu jinému se nepoužívají.

Záložka Autentizace s vyplněným vydavatelem, příjemcem, podpisovým klíčem a claimem s identitou

Přenos hodnot z tokenu do dialogu¶

V sekci Přenos hodnot z tokenu do dialogu každý řádek zkopíruje jednu hodnotu z ověřeného tokenu do proměnné, kterou pak dialog čte. Řádek přidáte tlačítkem Přidat mapování a vyplníte JWT claim a Kontextovou proměnnou, na kterou se má přenést.

JWT claim	Kontextová proměnná
`ps_number`	`$ps_number`
`segment`	`$segment`

Claim, který nenamapujete, se do dialogu nedostane vůbec.

Jeden claim namapovaný na kontextovou proměnnou dialogu, s diagramem vysvětlujícím přenos

Protože tyto hodnoty pocházejí z tokenu ověřeného platformou, nemůže je prohlížeč dodatečně přepsat — a právě proto na nich dialog může bezpečně stavět.

Na co pamatovat:

Čtou se pouze claimy na nejvyšší úrovni. Tečka je součástí názvu claimu, ne cesta do vnořeného objektu.
Claim, který token neobsahuje, se přeskočí a návštěvník zůstane přihlášený.
Pro názvy proměnných doporučujeme snake_case.
Namapovat lze nejvýše 10 claimů.

Info

Hodnota delší než 128 znaků se přeskočí a všechny přenášené hodnoty dohromady se musí vejít do 1 kB. Cokoli nad limit se do dialogu nikdy nedostane a neupozorní na to žádné hlášení.

Délka session a platnost tokenu¶

Pole	Co určuje
Délka session (sekundy)	Jak dlouho zůstane přihlášení platné, než si chat vyžádá od vaší stránky nový token. Přihlášení vždy skončí tím, co nastane dřív: touto dobou, nebo hodnotou `exp` v tokenu. 60–3600 sekund, výchozí 3600 (jedna hodina).
Nejdelší přijatá platnost tokenu (sekundy)	Omezuje, jak dlouho může jediný token udržet návštěvníka přihlášeného, bez ohledu na platnost, se kterou byl vydán. 60–43200 sekund, výchozí 43200 (12 hodin).
Tolerance časového posunu (sekundy)	Přípustný rozdíl mezi hodinami vašeho podpisového serveru a platformy. Token, který vypadá jako vydaný mírně v budoucnosti nebo jako právě vypršelý, je v rámci této tolerance přijat. 0–300 sekund, výchozí 60.

Tip

Doporučujeme, aby poskytovatel identity nastavoval vydávaným tokenům expiraci (exp). Bez ní se doba autorizace počítá od okamžiku vydání tokenu a je omezená pouze polem Nejdelší přijatá platnost tokenu (sekundy), což je podstatně hrubší hranice.

Volání přihlášení z vaší stránky¶

const result = await window.daktelaAiChat.authorize(
  jwt,
  async () => fetchFreshJwt(),   // zavolá se, když session vyprší
);

if (!result.authorized) {
  console.warn('Chat authorization failed:', result.reason);
}

O tom, jestli to v praxi funguje dobře, rozhodují tři věci:

Doporučený okamžik je načtení stránky, jakmile je token k dispozici — nikoli až když návštěvník otevře chat. Session patří jedné kartě prohlížeče, takže vracející se návštěvník žádnou nemá, dokud toto volání neproběhne. Pozdější volání je podporované a nic se neztratí: widget do té doby drží anonymní session a platforma ji sloučí pod ověřenou identitu. Stojí to však jedno kolo dotazů navíc a viditelné obnovení spojení.
Druhý parametr je funkce, kterou chat zavolá pro nový token po vypršení session. Musí vrátit token, který je ještě platný — a může to být i ten samý jako předtím: vyprší session chatu, ne váš token, takže uložený token, jehož platnost ještě neskončila, je v pořádku. Token s prošlou platností, prázdná hodnota, výjimka nebo funkce, která se nikdy nedokončí, návštěvníka odhlásí místo opakování pokusu.
Volání uspěje i tehdy, když ověření neprojde. Výsledek čtěte z polí authorized a reason, nikoli z výjimky.

Úplný přehled metod najdete na stránce Widget API.

Ověření nastavení¶

Záložka Autentizace obsahuje sekci Ověření nastavení, která přihlásí návštěvníka přímo v náhledu vedle sebe, a to přes stejné rozhraní window.daktelaAiChat.authorize(), jaké používá vaše stránka.

Buď zvolte Vygenerovat token — prohlížeč vytvoří dočasný pár klíčů a tlačítko Vložit do konfigurace vloží jeho veřejný klíč do nastavení — nebo zvolte Použít existující token a vložte JWT podepsaný klíčem, který už v konfiguraci je. Poté klikněte na Podepsat a ověřit.

Sekce ověření po úspěšném přihlášení v náhledu

Info

Ověřuje se publikovaná konfigurace, nikoli rozpracované změny — u okna, které už běží, je proto nutné nastavení nejprve uložit a publikovat. Výjimkou je okno, které dosud nikdo nepublikoval: tam se ověřuje rozpracovaná konfigurace, takže nastavení lze doladit ještě před prvním publikováním. Vznikne skutečná session i konverzace; pro jejich odlišení od ostrých lze v náhledu zapnout testovací režim.

Tlačítkem Odhlásit vrátíte náhled zpět k anonymnímu návštěvníkovi.

Odhlášení¶

window.daktelaAiChat.logout() se volá ve chvíli, kdy se návštěvník odhlásí z vašeho webu. Zneplatní session na serveru pro všechny karty i zařízení, nejen pro aktuální, a vrátí tento prohlížeč k anonymní identitě se smazanou lokální historií.

Dvě věci záměrně nedělá:

Neukončí konverzaci. Diskuze zůstane otevřená a v přepisu je označená poznámkou. Návštěvník v ní nemůže pokračovat anonymně, ale po opětovném přihlášení se k ní vrátí.
Nezapomene prohlížeč. Další anonymní návštěva je rozpoznána jako tentýž prohlížeč, který v té době už nevlastní nic z přihlášeného účtu.

Co dál?¶

Potřebujete úplný seznam metod, které může vaše stránka volat — otevření okna, přepnutí konverzace, předání kontextu, registrace nástrojů? Podívejte se na Widget API.