User Sessions

User Sessions#

The Widget SDK handles guests, visitors you know by name, and visitors signed in to your site. This page covers the session lifecycle — from sign-in to sign-out and switching between users on one browser.

How Sessions Work#

The widget gives every browser a random visitor id, kept inside the chatbox’s own storage. A visitor returning in the same browser sees their conversation; clearing storage starts a new visitor. Let the widget generate this id — never set it to a user id, email or anything guessable (see Guests & data never to send).

Sign-in — Identifying a User#

A signed-in visitor is recognised in one of three ways: the Gydr WordPress plugin, your identity provider, or a short-lived identity token your server signs and the widget fetches from an endpoint on your site (shown below). There is nothing to call when someone signs in — the widget asks your endpoint before the first message and whenever the token is about to expire. The full guide, with server code for Node.js, PHP and Python, is Identify signed-in visitors.

<!-- The same tag for guests and signed-in visitors -->
<script
  src="https://cdn.gydr.ai/widget.js"
  data-api-key="pk_live_YOUR_KEY"
  data-identity-endpoint="/gydr/identity-token"
  async
></script>

Sign-out — Automatic#

With data-identity-endpoint or Gydr.setIdentityTokenProvider(), sign-out needs no code. When your endpoint returns { "token": null }, the widget starts a new visitor with an empty conversation. The same happens when a different person signs in on the same browser (a token with a different sub): the previous conversation is cleared, and it can never continue for anyone else. A signed-in person’s past chats are shown only while they are signed in.

Clearing everything — Gydr.reset()#

reset() still clears all visitor data, destroys the widget and resets the SDK. Use it when you pass a fixed token with identify({ identityToken }) (which has no endpoint to ask), or when you want a complete wipe on a shared device.

function handleLogout() {
  Gydr.reset();          // 1. clear the chatbot
  auth.signOut();        // 2. your own sign-out
  Gydr.bubble({ apiKey: 'pk_live_YOUR_KEY' }); // 3. optional: a fresh guest widget
}

Switching Users (User A → User B)#

With an endpoint or provider, switching is automatic: once your site returns User B’s token, the widget sees a different sub and starts a new conversation. With a fixed token, reset first:

// User A signs out
Gydr.reset();

// User B signs in — token signed by your server for User B
Gydr.identify({ identityToken: tokenForUserB });
Gydr.bubble({ apiKey: 'pk_live_YOUR_KEY' });

What reset() Clears#