Identity Management

The Permutive SDK provides identity management to track users across sessions and connect data from multiple devices or touchpoints.

User ID

Aliases

identify()

Overview

User ID

Every user is automatically assigned a unique user ID by the SDK. This ID:

Is generated on first visit and persisted in a first-party cookie
Is unique to your domain (not shared across publishers)
Survives browser sessions and cookie clearing in most cases
Is used to track behavior and build cohorts

// Get the current user ID from localStorage
var userId = localStorage.getItem('permutive-id');
console.log('User ID:', userId);

The user ID is stored in localStorage with the key permutive-id. It works in all browsers, including Safari and Firefox which block third-party cookies.

Aliases

Setting Aliases

Use permutive.identify() to set user aliases:

// Set a single alias
permutive.identify([
  { tag: 'email_sha256', id: 'a1b2c3d4e5f6g7h8i9j0...' }
]);

// Set multiple aliases
permutive.identify([
  { tag: 'email_sha256', id: 'a1b2c3d4e5f6g7h8i9j0...' },
  { tag: 'internal_id', id: 'user_12345', priority: 1 },
  { tag: 'subscriber_id', id: 'sub_789', priority: 2 }
]);

Identity Record Structure

Each identity record has the following fields:

Field	Type	Required	Description
`tag`	string	Yes	The type of identifier (configured in dashboard)
`id`	string	Yes	The actual identifier value
`priority`	number	No	Resolution priority (lower = higher priority)
`expiry`	number	No	Expiration timestamp (Unix milliseconds)

Setting Identity

Basic Usage

// When user logs in
function onUserLogin(user) {
  permutive.identify([
    { tag: 'email_sha256', id: hashSHA256(user.email) }
  ]);
}

With Priority

// Set identities with explicit priority
permutive.identify([
  { tag: 'email_sha256', id: emailHash, priority: 0 },      // Highest priority
  { tag: 'internal_id', id: 'user_12345', priority: 1 },
  { tag: 'device_id', id: 'device_abc', priority: 2 }       // Lowest priority
]);

With Expiry

Set an expiration time for temporary identities:

// Identity expires in 24 hours
var expiryTime = Date.now() + (24 * 60 * 60 * 1000);

permutive.identify([
  { tag: 'session_token', id: 'session_abc123', expiry: expiryTime }
]);

Identity Resolution

When you call identify():

permutive.identify([
  { tag: 'email_sha256', id: 'abc123...' }
]);

The SDK:

Sends the alias to Permutive servers
Server checks if this alias exists for another user
If found, user profiles are merged
SDK receives updated cohorts and state
Future events are linked to the resolved identity

Common Identity Patterns

Login Event
Registration
Newsletter Signup
Third-Party Identity

// Track login and set identity
function handleLogin(user) {
  // Set identity
  permutive.identify([
    { tag: 'email_sha256', id: hashSHA256(user.email) },
    { tag: 'internal_id', id: user.id }
  ]);

  // Track login event
  permutive.track('Login', {
    method: 'email',
    is_new_user: user.isNew
  });
}

// Set identity on new registration
function handleRegistration(user) {
  permutive.identify([
    { tag: 'email_sha256', id: hashSHA256(user.email) },
    { tag: 'internal_id', id: user.id }
  ]);

  permutive.track('Registration', {
    signup_source: user.source,
    plan_type: user.plan
  });
}

// Set identity from newsletter form
function handleNewsletterSignup(email) {
  permutive.identify([
    { tag: 'email_sha256', id: hashSHA256(email) }
  ]);

  permutive.track('NewsletterSignup', {
    list: 'daily_digest'
  });
}

// Set identity from third-party provider (e.g., ID5, RampID)
function setThirdPartyIdentity(providerId, identityValue) {
  permutive.identify([
    { tag: providerId, id: identityValue }
  ]);
}

// Example with ID5
setThirdPartyIdentity('id5', 'ID5-abc123...');

Hashing Requirements

Never send plain-text PII to Permutive. Always hash email addresses and other personal identifiers before passing them to identify().

SHA-256 Hashing

Email addresses should be hashed using SHA-256:

// Using Web Crypto API (modern browsers)
async function hashSHA256(email) {
  const normalized = email.toLowerCase().trim();
  const encoder = new TextEncoder();
  const data = encoder.encode(normalized);
  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
  const hashArray = Array.from(new Uint8Array(hashBuffer));
  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
}

// Usage
hashSHA256('user@example.com').then(function(hash) {
  permutive.identify([
    { tag: 'email_sha256', id: hash }
  ]);
});

Hashing Best Practices

Normalize before hashing: Lowercase and trim whitespace
Use consistent algorithm: SHA-256 is standard
Hash on server if possible: Avoids exposing raw email in client code
Same hash everywhere: Use identical normalization across all touchpoints

Resetting Identity

When a user logs out, reset their identity:

function handleLogout() {
  // Reset all SDK state
  permutive.reset();

  // Or just track logout without reset
  // permutive.track('Logout', {});
}

permutive.reset() clears all user data including cohorts and identity. Use it when a user explicitly logs out or requests data deletion.

Cross-Domain Identity

For tracking users across multiple domains you own:

// On domain-a.com
permutive.identify([
  { tag: 'cross_domain_id', id: 'shared_user_123' }
]);

// On domain-b.com (same identifier)
permutive.identify([
  { tag: 'cross_domain_id', id: 'shared_user_123' }
]);

// Permutive will link the user profiles

Cross-domain identity requires using the same identity tag and value across both domains. Contact your Customer Success Manager to configure cross-domain tracking.

Identity Events

Listen for identity changes:

// Listen for identity resolution events
permutive.on('SegmentEntry', function(event) {
  // User entered a new segment after identity resolution
  console.log('Entered segment:', event.properties.segment);
});

Troubleshooting

Identity not persisting

Problem: User appears as new visitor on each session.Solutions:

Check that cookies aren’t being blocked
Verify cookie domain configuration
Check for browser privacy settings (private mode)
Ensure permutive-id cookie exists in Application > Cookies

identify() not working

Problem: Calling identify() but user data not connected.Solutions:

Verify identity tags are configured in dashboard
Check that identity values match exactly (case-sensitive)
Enable debug mode to see identify requests
Ensure SDK is initialized before calling identify

Duplicate users

Problem: Same person appears as multiple users.Solutions:

Ensure consistent identity values across touchpoints
Use same hashing algorithm everywhere
Set identity as early as possible in the session
Check priority settings if multiple identities conflict

Event Properties

Structure event data correctly

Cohorts & Activations

How identity affects cohort membership

Consent Management

Identity and GDPR consent

Identity Graph

Platform identity resolution

Get Started

Products

Deployment

Governance

Identity Management

User ID

Aliases

identify()

Overview

User ID

Aliases

Setting Aliases

Identity Record Structure

Setting Identity

Basic Usage

With Priority

With Expiry

Identity Resolution

Common Identity Patterns

Hashing Requirements

SHA-256 Hashing

Hashing Best Practices

Resetting Identity

Cross-Domain Identity

Identity Events

Troubleshooting

Event Properties

Cohorts & Activations

Consent Management

Identity Graph

User ID

Aliases

identify()

​Overview

​User ID

​Aliases

​Setting Aliases

​Identity Record Structure

​Setting Identity

​Basic Usage

​With Priority

​With Expiry

​Identity Resolution

​Common Identity Patterns

​Hashing Requirements

​SHA-256 Hashing

​Hashing Best Practices

​Resetting Identity

​Cross-Domain Identity

​Identity Events

​Troubleshooting

​Related Documentation

Event Properties

Cohorts & Activations

Consent Management

Identity Graph

Overview

User ID

Aliases

Setting Aliases

Identity Record Structure

Setting Identity

Basic Usage

With Priority

With Expiry

Identity Resolution

Common Identity Patterns

Hashing Requirements

SHA-256 Hashing

Hashing Best Practices

Resetting Identity

Cross-Domain Identity

Identity Events

Troubleshooting

Related Documentation