User Identification
Told tracks each unique visitor to your website or app as a SourceAuthor — an identity within a specific source.
How user tracking works
Anonymous users
When a person first visits, the SDK creates a SourceAuthor with a generated anonymousID. This ID is stored locally:
| Platform | Storage |
|---|---|
| Web | Cookies |
| Android | SharedPreferences |
| iOS | Keychain |
The anonymous user is recognized on future visits using this stored identifier.
Identified users
When you call the identify function, the SourceAuthor is updated with a userId and custom traits. The userId takes priority over anonymousID for identification.
All activity collected while the user was anonymous is associated with their identified profile.
What is stored per user
| Field | Description |
|---|---|
anonymousID | Auto-generated anonymous identifier |
userId | Custom ID you provide via identify |
name | Display name |
language | Browser/device language (e.g., "EN") |
deviceType | desktop, tablet, or phone |
os | Operating system |
version | App/OS version |
customData | Key-value object with any traits you send |
nbSessions | Number of visits (auto-tracked) |
dateLastAction | Timestamp of last activity |
dateLastAnswer | Timestamp of last survey response |
companies | List of associated companies/groups |
Sessions
A session represents a single visit. The session counter (nbSessions) increments automatically. A new session starts after 30 minutes of inactivity.
Reset (logout)
When you call the reset function, a new anonymous SourceAuthor is created with a fresh anonymousID. The previous user's data is preserved separately.
The identify function
Web
told('identify', {
id: 'user_123',
name: 'Jane Doe',
email: '[email protected]',
plan: 'pro'
});
Android (Kotlin)
Told.identify(mapOf(
"id" to "user_123",
"name" to "Jane Doe",
"email" to "[email protected]"
))
iOS (Swift)
Told.identify(properties: [
"id": "user_123",
"name": "Jane Doe",
"email": "[email protected]"
])
Reserved traits
These traits have special handling in Told:
| Trait | Type | Description |
|---|---|---|
id | String | Required. Unique user ID — stored as userId on the SourceAuthor |
name | String | Display name |
firstName | String | First name (used for name fallback) |
lastName | String | Last name (used for name fallback) |
email | String | Email address |
username | String | Username |
phone | String | Phone number |
avatar | String | Avatar URL |
language | String | Language code (e.g., "en") — overrides browser detection |
website | String | User's website URL |
description | String | Bio or description |
createdAt | Date | Account creation date (ISO-8601) |
address | Object | Postal address (city, country, postalCode, state, street) |
Any other key-value pairs you pass are stored in customData and can be used for audience targeting.
Hidden fields
You can also pass user data via hidden fields at init time, without calling identify:
told('init', 'SOURCE_ID', {
hidden_fields: { name: 'John', email: '[email protected]', plan: 'pro' }
});
Hidden fields appear in survey reports alongside the respondent's answers.
Import users
Bulk import users from your database:
- Go to your source's Audience section
- Click Import
- Upload a JSON or CSV file
Each entry must include a mandatory id field. You can include a groups field containing a list of group IDs to associate. If a group doesn't exist, it will be created.
Events tracked per user
The SDK automatically sends events for user actions:
| Event | When |
|---|---|
IDENTIFY | identify function called |
RESET | reset function called |
START_SESSION | New session starts |
CHANGE_PAGE | User navigates to a new page/screen |
ON_CLICK | User clicks an element (if click tracking enabled) |
ON_SCROLL | User scrolls (if scroll tracking enabled) |
CUSTOM_EVENT | addEvent / trackEvent called |
START_SURVEY | User sees a survey |
NEW_ANSWER | User answers a question |
REACH_END | User completes a survey |
CLOSE_SURVEY | User closes a survey |
SKIPPED | User skips a survey |
START_PRODUCT_TOUR | User starts a product tour |
Viewing users
All users are visible in the Audience section of your source. You can view individual profiles with their traits, events, answers, and group memberships.