Fullstory Identify Users API

Implementation Files: This document covers core concepts. For code examples, see:
- [SKILL-WEB.md](./SKILL-WEB.md) — JavaScript/TypeScript (Browser)
- [SKILL-MOBILE.md](./SKILL-MOBILE.md) — iOS, Android, Flutter, React Native

Overview

Fullstory's User Identification API allows developers to associate session data with your own unique customer identifiers. By calling setIdentity, you link a user's Fullstory session to their identity in your system, enabling you to:

• Search for sessions by customer ID
• View all sessions for a specific user across devices
• Connect Fullstory data with your internal analytics and CRM systems
• Attribute behavior patterns to known users

Core Concepts

When Identification Happens

• On Login: Call setIdentity immediately after a successful authentication
• On App/Page Load (Already Authenticated): Call setIdentity on every app launch/page load if the user is logged in
• After Authentication Redirects: Ensure identification persists across OAuth/SSO redirects

User Identity vs Anonymous Sessions

• Anonymous Session: Default state before setIdentity is called. User is tracked but not linked to your system.
• Identified Session: After setIdentity, the session is permanently linked to the provided uid.

How Identification Works (Session Linking)

1. Before identification: All sessions from the same device are linked together anonymously
2. When setIdentity is called: ALL previous anonymous sessions are retroactively merged into the identified user
3. Cross-device linking: If the same uid is used on different devices, all sessions across all devices are linked

┌─────────────────────────────────────────────────────────────────────────┐
│                    Session Merging on Identification                     │
├─────────────────────────────────────────────────────────────────────────┤
│  Day 1: Anonymous visit          → "Anonymous User"                     │
│  Day 3: Anonymous visit          → Same anonymous user                  │
│  Day 7: User logs in, setIdentity(uid: "user_456")                      │
│         ↓                                                               │
│  Result: ALL sessions (Day 1, 3, 7) now linked to "user_456"           │
└─────────────────────────────────────────────────────────────────────────┘

Important: This means a user's entire journey from first visit through conversion can be tracked, even if they only identify on their 5th session.

Re-identification Behavior

• CRITICAL: You cannot change a user's identity once assigned within a session
• If you call setIdentity with a different uid, Fullstory automatically splits into a new session
• This is by design to maintain data integrity and prevent identity pollution

Key Principles

1. Use a stable, unique identifier (database ID, UUID) — never use PII like email as the uid
2. Call setIdentity as early as possible after authentication
3. Include meaningful properties for searchability (displayName, email)
4. Handle logout properly by calling anonymize

setIdentity vs setProperties (User)

Important: The properties object in setIdentity is a convenience — you can include initial properties when identifying. However, for updating properties after identification or for anonymous users, use setProperties with type: 'user' instead. See the fullstory-user-properties skill for details.

UID Requirements

Good UIDs

• Database primary key: usr_a1b2c3d4e5
• UUID: 550e8400-e29b-41d4-a716-446655440000
• Hashed identifier: sha256_abc123...

Bad UIDs

• Email: [email protected] ❌
• Phone: +1-555-123-4567 ❌
• Name: John Smith ❌

Special Property Fields

These fields have special treatment in the Fullstory UI and should always be included when available.

Supported Property Types

Rate Limits

Exceeding limits may result in dropped calls.

Authentication State Machine

┌─────────────────┐
│  Anonymous      │ ← Initial state (no setIdentity called)
│  Session        │
└────────┬────────┘
         │ User logs in
         ▼
┌─────────────────┐
│  Identified     │ ← setIdentity({ uid: 'xxx' }) called
│  Session        │
└────────┬────────┘
         │ User logs out
         ▼
┌─────────────────┐
│  New Anonymous  │ ← setIdentity({ anonymous: true }) called
│  Session        │   (or platform equivalent)
└─────────────────┘

Best Practices

1. Identification Timing

• ✅ Call setIdentity immediately after successful authentication
• ✅ Call on every app launch/page load if user is already authenticated
• ❌ Don't call before authentication completes
• ❌ Don't call on every user interaction

2. Property Design

• ✅ Always include displayName and email
• ✅ Add business-relevant properties (plan, role, company)
• ✅ Use explicit schema for non-string types
• ❌ Don't include sensitive data that shouldn't be in Fullstory

3. Account Switching

For apps where users can switch accounts:

1. Call anonymize/logout first
2. Then identify as the new user
3. Track which account is currently active

4. Progressive Identification

For guest checkout → account creation flows:

1. Keep user anonymous during guest checkout
2. Identify when they create an account
3. All prior anonymous activity links automatically

Troubleshooting

Sessions Not Linking to User

Unexpected Session Splits

Properties Not Appearing

Key Takeaways for Agent

When helping developers implement User Identification:

1. Always emphasize:

- Use stable database IDs as uid, never PII - Call setIdentity AFTER successful authentication - Include displayName and email as properties - You cannot change identity without anonymizing first

1. Common mistakes to watch for:

- Using email as uid - Identifying before auth completes - Calling setIdentity excessively - Trying to update identity instead of using setProperties - Missing displayName/email properties

1. Questions to ask developers:

- What's your unique user identifier? (database ID, UUID) - When does authentication complete in your flow? - Do users switch between accounts in your app? - What user attributes are important for segmentation?

1. Platform routing:

- Web (JavaScript/TypeScript) → See SKILL-WEB.md - iOS (Swift/SwiftUI) → See SKILL-MOBILE.md § iOS - Android (Kotlin) → See SKILL-MOBILE.md § Android - Flutter (Dart) → See SKILL-MOBILE.md § Flutter - React Native → See SKILL-MOBILE.md § React Native

Reference Links

• Identify Users (Web): https://developer.fullstory.com/browser/identification/identify-users/
• Identify Users (iOS): https://developer.fullstory.com/mobile/ios/identification/identify-users/
• Identify Users (Android): https://developer.fullstory.com/mobile/android/identification/identify-users/
• Identify Users (Flutter): https://developer.fullstory.com/mobile/flutter/identification/identify-users/
• Identify Users (React Native): https://developer.fullstory.com/mobile/react-native/identification/identify-users/
• Anonymize Users: https://developer.fullstory.com/browser/identification/anonymize-users/
• Help Center - Identifying Users: https://help.fullstory.com/hc/en-us/articles/360020623294-Identifying-users