Identifying Users

By default, Pulseahead tracks responses anonymously using a locally stored unique identifier. The identify method allows you to link these responses to a specific user in your system. That linkage powers cross-device tracking, user-level analytics, and segment-based targeting.

Add the base snippet first: Install the script walks through Project ID and placement; Script & Initialization is the technical reference for the same snippet.

The identify Call

Call identify after the SDK has been initialized, ideally immediately after your application knows the user’s identity (e.g., after login).

window.pulseahead("identify", "USER_ID", {
  plan: "pro",
  role: "admin",
  signupDate: "2024-01-15",
});

Arguments

Argument	Type	Description
userId	string	Required. Your internal user ID (e.g., UUID from your database).
traits	object	Optional. Key-value pairs representing user attributes used for segment targeting.

How Identification Works

1. User Resolution: The SDK sends the userId and traits to the Pulseahead API.
2. Session Linking: If the user was previously anonymous, their history is merged into the identified user record.
3. Attribute Storage: The traits (e.g., plan, role) are stored and used to evaluate Targeting rules for active surveys.

User Attributes (Traits)

Passing user attributes lets Pulseahead evaluate segment rules and any other targeting that depends on traits. Define user segments in the dashboard from these attributes, then attach them on each survey’s Targeting tab.

Common attributes to pass:

• plan: (e.g., 'free', 'pro', 'enterprise')
• role: (e.g., 'admin', 'editor', 'viewer')
• signupDate: (ISO string)
• teamId: (UUID)

Best Practices

• Consistency: Use the same key names and value types as in your segment rules in the dashboard.
• Privacy: Avoid passing sensitive personal information (PII) like email addresses, etc.
• Timing: Call identify on every page load after the initial config call to ensure traits are up to date.

The logout Call

When a user logs out of your application, call the logout method. This clears the user’s identification and generates a new anonymous ID for the current session.

window.pulseahead("logout");

This ensures that:

• Subsequent feedback is not attributed to the previous user.
• Any targeting rules based on the previous user’s attributes are reset.

Where identification shows up

• User Timeline — open User History from the Response Feed once cards show Identified User.
• Manual trigger — showSurvey still validates surveys that are limited to identified users.