iOS SDK - Setting a User ID

Follow
Avatar
Jared Ornstead
Updated

Setting a User ID

Send your internal user ID to Singular to enable cross-device tracking and user-level data reporting.

Note: If you use Singular's Cross-Device solution , you must collect the User ID across all platforms.

User ID Requirements

Privacy and Best Practices

Follow these guidelines when implementing user ID tracking to ensure privacy compliance and proper cross-device measurement.

  • No PII: The User ID should not expose Personally Identifiable Information (PII) such as email addresses, usernames, or phone numbers. Use a hashed value unique to your first-party data.
  • Consistency Across Platforms: The User ID value must be the same internal identifier you capture across all platforms (Web/Mobile/PC/Console/Offline) for accurate cross-device measurement.
  • First-Party Data: Singular includes the User ID in user-level exports, ETL, and Internal BI postbacks (if configured). The User ID is first-party data and is not shared with third parties.
  • Persistence: The User ID persists until explicitly unset using unsetCustomUserId() or until the app is uninstalled. Closing or restarting the app does not clear the User ID.

Implementation Overview

When to Set the User ID

Use setCustomUserId() to set the user identifier and unsetCustomUserId() to clear it during logout.

Best Practice: If multiple users share a single device, implement a logout flow that calls setCustomUserId() on login and unsetCustomUserId() on logout.

If you already know the user ID when the app opens, call setCustomUserId() before initializing the Singular SDK. This ensures Singular receives the User ID from the first session. However, the User ID is typically unavailable until the user registers or logs in, in which case call setCustomUserId() after the registration or authentication flow completes.

SDK Methods

Set Custom User ID

Send your internal user ID to Singular for cross-device tracking and user-level reporting.

Swift Objective-C 
// Set the user ID after login or registration
Singular.setCustomUserId("custom_user_id")

Method Signature: 

+ (void)setCustomUserId:(NSString *)customUserId;

+setCustomUserId: returns void — there is no success/failure signal at the call site. The User ID is attached to the next session and event the SDK sends.

The similarly-named +setDeviceCustomUserId: is annotated __attribute__((deprecated)) and exists only for legacy compatibility. Always call +setCustomUserId: in new code.

Unset Custom User ID

Clear the user ID when a user logs out to ensure accurate session tracking for multi-user devices.

Swift Objective-C 
// Unset the user ID on logout
Singular.unsetCustomUserId()

Method Signature: 

+ (void)unsetCustomUserId;