Teardown | Kill Old App Versions Instantly. Ship Without Fear. Build Boldly.

The Identity client manages user sessions, device identification, and authentication state.

Overview

The SDK automatically identifies devices on initialization. You can optionally associate users with devices by calling identify() with user information.

Session Structure

interface Session {
  session_id: string;  // Unique session identifier
  device_id: string;   // Stable device identifier
  user_id: string;     // User or persona identifier
  token: string;       // Authentication token
}

Basic Usage

Identify a User

const { core } = useTeardown();

const handleLogin = async () => {
  const result = await core.identity.identify({
    user_id: 'user-123',
    email: 'user@example.com',
    name: 'John Doe',
  });

  if (result.success) {
    console.log('Identified:', result.data.session_id);
  } else {
    console.error('Failed:', result.error);
  }
};

Get Current Session

// Imperative
const session = core.identity.getSessionState();

// Reactive (hook)
const session = useSession();

if (session) {
  console.log('Device:', session.device_id);
  console.log('User:', session.user_id);
}

Reset Identity

Clear the current session and device association:

core.identity.reset();

Refresh Session

Re-identify to refresh session data (only works if already identified):

const result = await core.identity.refresh();

Identity State

The identity client maintains a state machine:

type IdentifyState =
  | { type: 'unidentified' }
  | { type: 'identifying' }
  | { type: 'identified'; session: Session; version_info: VersionInfo };

const unsubscribe = core.identity.onIdentifyStateChange((state) => {
  switch (state.type) {
    case 'unidentified':
      // Show login screen
      break;
    case 'identifying':
      // Show loading
      break;
    case 'identified':
      // Navigate to app
      console.log('Session:', state.session);
      break;
  }
});

// Cleanup
unsubscribe();

Persona Object

When identifying, you can provide optional user information:

interface Persona {
  user_id?: string;   // Your system's user ID
  email?: string;     // User email
  name?: string;      // Display name
}

All fields are optional. If no persona is provided, the device is identified anonymously.

Device ID

The SDK generates a stable device ID that persists across app sessions:

const deviceId = await core.device.getDeviceId();

The device ID is:

Generated once per device
Persisted in storage
Used for all API calls
Stable across app updates

Version Info

The identify response includes version information used for force updates:

if (state.type === 'identified') {
  const status = state.version_info.status;
  // 'UP_TO_DATE' | 'UPDATE_AVAILABLE' | 'UPDATE_RECOMMENDED' | 'UPDATE_REQUIRED' | 'DISABLED'
}

Error Handling

const result = await core.identity.identify({ user_id: '123' });

if (!result.success) {
  switch (result.error) {
    case 'Network error':
      // Handle offline
      break;
    default:
      // Handle other errors
      console.error(result.error);
  }
}

Best Practices

Call identify on login - Associate users with their devices
Call reset on logout - Clear session data
Handle offline - The SDK caches session data for offline use
Use useSession hook - For reactive UI updates

Identity

On this page