Visitors

What are Visitors?

Visitors are automatically created when someone loads your application with the Cossistant SDK. They represent anonymous users before they're identified as contacts.

Every visitor is unique per device/browser, persisting across page loads and sessions.

How Visitors are Tracked

Cossistant maintains anonymous visitor identity with a website-scoped ID:

• LocalStorage: Stores a generated visitor ULID for the current website
• Automatic creation: No setup required—visitors are created on first load

Cossistant does not use browser fingerprinting as a fallback identity. A cleared browser profile, private window, different browser, or different device creates a different anonymous visitor until you identify that person.

This means a visitor on desktop and the same person on mobile will be two different visitors until they're identified.

Anonymous by Default

Visitors start anonymous with no personal information:

• No name, email, or external ID until you identify the visitor
• Technical and acquisition context can include language, timezone, browser, operating system, device type, screen/viewport, current page, referrer, campaign/click identifiers, and server-enriched location
• Can start conversations without authentication
• Perfect for public-facing pages or logged-out users

Visitor Properties

Each visitor has:

• id: Unique identifier for this visitor
• language: Browser language (e.g., "en-US")
• timezone: Browser timezone (e.g., "America/New_York")
• isBlocked: Whether this visitor has been blocked from support
• contact: The associated contact (null until identified)

Identifying Visitors

Transform anonymous visitors into identified contacts when users authenticate:

Using the Component (Server Components)

Copyimport { IdentifySupportVisitor } from "@cossistant/next/identify-visitor";
import { auth } from "@/lib/auth";
import { headers } from "next/headers";
 
export default async function DashboardLayout({ children }) {
  const session = await auth.api.getSession({
    headers: await headers(),
  });
 
  return (
    <div>
      {session?.user && (
        <IdentifySupportVisitor
          externalId={session.user.id}
          email={session.user.email}
          name={session.user.name}
        />
      )}
      {children}
    </div>
  );
}

Using the Hook (Client Components)

Copy"use client";
 
import { useVisitor } from "@cossistant/next/hooks";
import { useEffect } from "react";
 
export function AuthHandler({ user }) {
  const { identify } = useVisitor();
 
  useEffect(() => {
    if (!user) {
      return;
    }
 
    void identify({
      externalId: user.id,
      email: user.email,
      name: user.name,
    });
  }, [user?.id, user?.email, user?.name, identify]);
 
  return null;
}

Run identification whenever the authenticated user's stable identity changes. Do not skip it merely because the browser already has a contact: on a shared browser, that contact may belong to the previous account. The component form is the simpler declarative default; if your application swaps accounts without remounting its authenticated layout, use the hook pattern above so the stable identity change always triggers an explicit identification request.

Tell users which support, analytics, and acquisition fields your application collects, keep only the context your team needs, and apply your own consent, retention, and deletion requirements.

Once identified, all conversations and data are linked to the contact, even across different devices.

Use a stable externalId from your own user records as the restore key. When the same user logs in after a reinstall, storage loss, or on another device, identifying with that externalId gives the new visitor access to the contact's existing conversation history. You do not need to store Cossistant's visitor ID for logged-in users.

Learn More

• Contacts: Identified visitors with metadata and cross-device support
• IdentifySupportVisitor: Component for visitor identification
• useVisitor: Hook for programmatic visitor control