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 uses a combination of techniques to maintain visitor identity:

• LocalStorage: Stores a unique visitor ID in the browser
• Fingerprinting: Browser and device characteristics for additional persistence
• Automatic creation: No setup required—visitors are created on first load

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
• Only browser-derived data (language, timezone)
• 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";
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";
import { useEffect } from "react";
 
export function AuthHandler({ user }) {
  const { visitor, identify } = useVisitor();
 
  useEffect(() => {
    if (user && !visitor?.contact) {
      identify({
        externalId: user.id,
        email: user.email,
        name: user.name,
      });
    }
  }, [user, visitor?.contact, identify]);
 
  return null;
}

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

Learn More

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