Identifiers

An identifier is the string you pass to identify() to tag a session with a user identity. It's how you link anonymous visitors to real users in your system.

What makes a good identifier?

Anything stable, unique, and safe to log. Common choices:

IdentifierGoodAvoid
Internal user ID✅ Opaque, stable, uniqueCan't filter by email in the dashboard
Email address✅ Easy to search❌ Changes if user updates email
Phone number✅ Works for WhatsApp-first apps❌ Privacy-sensitive
Username / handle⚠️ Unique but mutableChanges on rename
UUID from signup✅ Never changesLess human-readable in dashboard

Best practice: pass your internal user ID. Attach email / name / plan as traits so you can still search and filter.

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

What the SDK does with it

  1. Stores the identifier on the current session (in memory).
  2. Emits an identify event into the event buffer.
  3. Future events in this session and all subsequent sessions from the same visitor carry the identifier.
  4. If the identifier is too long (> 256 characters), the SDK truncates it.

Three ways to identify

1. Declarative — useIdentify() (React, recommended)

import { useIdentify } from "@galacha/react";
 
function Shell() {
  const { user } = useAuth();
  useIdentify(user?.id, { email: user?.email });
  return <Routes />;
}

Re-runs whenever user.id changes. Safe with null.

2. Imperative — useGalacha().identify()

const { identify } = useGalacha();
 
const handleLogin = async () => {
  const user = await api.login(email, password);
  identify(user.id, { email: user.email, plan: user.plan });
};

3. Inline — on Provider mount

<GalachaProvider
  projectKey="..."
  identifier={currentUser?.id}
  traits={{ email: currentUser?.email }}
/>

Good for apps that know the user at mount time (SSR with auth cookie).

Web SDK direct usage

If you loaded via <script> tag:

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

Two positional arguments: a string user ID, an optional traits object.

React Native

import Galacha from "@galacha/react-native";
 
Galacha.identify(String(user.id), {
  email: user.email,
  name: user.name,
});

Re-identifying

Calling identify() with a different user ID on the same session updates the identifier going forward. Older events in the session keep the old identifier. Common case: user switches accounts.

// Account A events → linked to user_a
identify("user_a", { email: "a@example.com" });
 
// ... interactions ...
 
// Account B events → linked to user_b
identify("user_b", { email: "b@example.com" });

Un-identifying?

No public API. Closest equivalent: call stop() and reload. For logout flows, the simpler pattern is to skip stop() entirely and let the next login call identify() with the new user.

Related