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.
// Set the user ID after login or registration
Singular.setCustomUserId("custom_user_id")// Set the user ID after login or registration
Singular.setCustomUserId("custom_user_id");Method Signature:
public void setCustomUserId(String customUserId)Unset Custom User ID
Clear the user ID when a user logs out to ensure accurate session tracking for multi-user devices.
// Unset the user ID on logout
Singular.unsetCustomUserId()ode class="="java"// Unset the user ID on logout Singular.unsetCustomUserId();
Method Signature:
public void unsetCustomUserId()Advanced Features
Custom User ID Device Mapping
Map the User ID to Singular's mobile device tracking identifier for server-to-server integrations.
Important: This advanced Enterprise feature is only available in exceptional cases. Consult with a Singular Solution Engineer before implementing it.
Singular can receive additional mobile event tracking data via server-to-server integration. To utilize this feature, you must map the User ID to Singular's mobile device tracking identifier.
Note: Call this method as soon as possible after initializing the Singular SDK or once you have the User ID.
Implementation
Use setDeviceCustomUserId() to set the custom user ID and
map
it to Singular's tracking identifier.
// Map user ID to device identifier for S2S integration
Singular.setDeviceCustomUserId("custom_user_id")// Map user ID to device identifier for S2S integration
Singular.setDeviceCustomUserId("custom_user_id");Method Signature:
public void setDeviceCustomUserId(String customUserId)Description: Sets the custom user ID (same as login) and maps it to Singular's tracking identifier for server-to-server event attribution.