Skip to main content
Important: Please ensure your CMP configuration includes new Vendor ID 1469 for 1st Party data tracking. Additionally, include Vendor ID 301 if cookie sync is enabled. Learn more
The setUserIdentities method is used to identify users by associating them with specific identifiers (like email, phone number, or your own internal IDs). This is crucial for cross-session user tracking and building comprehensive user profiles. Why use it?
  • User Stitching: Allows Zeotap to link user activity across different sessions or devices when a known identifier is provided.
  • Data Enrichment: Provides key identifiers needed for potential data enrichment processes.
  • Audience Building: Enables creating audiences based on specific known identifiers.
PersistenceIdentifiers set using setUserIdentities() are persisted and automatically included in the user node of the payload for all subsequent events sent during the user’s session(s).

​
Syntax

Collect.getInstance()?.setUserIdentities(_ identities: [String: Any], _ callback: ResponseCallback?)

​
Parameters

ParameterTypeRequiredDescription
identities[String: Any]YesA dictionary containing user identity key-value pairs
callbackResponseCallback?OptionalCallback to handle function response

​
Understanding Identifier Types

You can send different categories of identifiers:
  1. Personal Identifiable Information (PII): Standardized identifiers like email or phone number. These can be sent raw or pre-hashed.
  2. Custom Identities: Your own first-party identifiers (e.g., crmId, loyaltyId). Hashing configurations don’t apply to these.

​
Choosing Your Hashing Strategy

Before using setUserIdentities, you must decide how PII (like email and phone numbers) will be handled regarding hashing. This choice affects your SDK configuration and the keys you use in the setUserIdentities call. Click on each scenario below for details:

​
Sending Raw Identifiers

​
Sending Pre-Hashed Identifiers

​
SDK Performs Hashing

​
PII Identifier Key Reference

PII PropertyKey to Use if Sending RAW
(Scenarios 1 & 3)		Key to Use if Sending PRE-HASHED
(Scenario 2 Only)		Description & Important Notes
Emailemailemail_sha256_lowercase,email_sha256_uppercase, email_md5_lowercase, email_md5_uppercase, email_sha1_lowercase, email_sha1_uppercaseUser’s email address. Use the email key for raw input. Use one of the specific hashed keys (like email_sha256_lowercase) if you provide a pre-hashed value.
Cell Phonecellnocellno_without_country_code_sha256, cellno_without_country_code_md5, cellno_without_country_code_sha1, cellno_with_country_code_sha256, cellno_with_country_code_md5,cellno_with_country_code_sha1User’s cell phone number.
For Raw: Use cellno. Recommended Format: For best results, use '+[code] [number]' (e.g., '+1 5551234567').
For Pre-Hashed: Use the specific key matching your hash type (e.g., cellno_with_country_code_sha256).
Login IDloginidloginid_sha256_lowercase,loginid_sha256_uppercase, loginid_md5_lowercase, loginid_md5_uppercase, loginid_sha1_lowercase, loginid_sha1_uppercaseUser’s login ID. Use the loginid key for raw input. Use one of the specific hashed keys if you provide a pre-hashed value.
How to Use This Table:
  1. Identify the PII Property you want to send (e.g., Email, Cell Phone).
  2. Determine your Hashing Scenario:
    • Scenario 1 (Raw) or 3 (SDK Hashing): Look at the “Key to Use if Sending RAW” column. Use that key (e.g., email, cellno) and provide the raw value. Pay attention to the recommended format for cellno.
    • Scenario 2 (Pre-Hashed): Look at the “Key to Use if Sending PRE-HASHED” column. Choose the key that matches the exact hashing algorithm and format you used (e.g., email_sha256_lowercase, cellno_with_country_code_sha256) and provide the pre-computed hash value.
  3. Remember: For a single PII property (like email), you will use either the raw key or a hashed key in your setUserIdentities call, never both simultaneously for the same piece of information.

​
Custom Identities

You can include any other key-value pairs representing your own first-party identifiers. These are sent as-is and are not affected by the PII hashing configurations. 
Collect.getInstance()?.setUserIdentities([
    // PII Keys (Raw or Hashed depending on scenario)
    "email": "user@example.com",
    // Custom Keys
    "crmId": "12345-ABC",
    "visitorId": "analytics_client_id_here"
])

​
Set User identities with callbacks

You can also set Identities with Callback function as shown below. The data parameter is an object that contains status and message which helps to debug the status of the function call. 
Collect.getInstance()?.setUserIdentities([
    // PII Keys (Raw or Hashed depending on scenario)
    "email": "user@example.com",
    // Custom Keys
    "crmId": "12345-ABC",
    "visitorId": "analytics_client_id_here"
], {data in 
    // Implement function to handle response
    // [status: "SUCCESS", message: "User identities set successfully"]
})

​
Removing User identities

This method is used to remove user identities that are set by the setUserIdentities method. This will remove all the identities from the storage as well from all subsequent events that made by SDK. 
Collect.getInstance()?.unSetUserIdentities()

​
Best Practices

  1. Call Early: Set user identities as soon as they are available, typically after user login or app launch if the user is already authenticated.
  2. Use Consistent Identifiers: Ensure the same identifiers are used across all platforms (Web, iOS, Android) for the same user.
  3. Include Multiple Identities: Provide multiple identity types when available to improve user matching accuracy.
  4. Handle Privacy: Ensure you have proper user consent before collecting and sending personal identifiers.

​
Privacy Considerations

  • Always ensure you have user consent before collecting personal identifiers
  • Follow local privacy regulations (GDPR, CCPA, etc.)
  • Consider hashing sensitive identifiers if required by your privacy policy

​
Error Handling

The method will fail silently if:
  • The SDK is not initialized
  • Invalid data types are provided
  • Network connectivity issues occur (data will be queued for later transmission)
Last modified on June 25, 2026