Setting a User ID

Send your internal user ID to Singular to enable cross-device tracking and user-level data reporting. This identifier links user activity across sessions and devices for comprehensive attribution analysis.

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. Choose the implementation approach based on when the user ID becomes available in your app flow.

If you already know the user ID when the app opens (e.g., user has persistent login), configure it using withCustomUserId() 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. Call this method immediately after successful authentication to ensure all subsequent events are associated with the user.

// Set the user ID after login or registration
cordova.plugins.SingularCordovaSdk.setCustomUserId('user_123456');

Method Signature:

setCustomUserId(customUserId: string): void

Example: Set User ID After Login

Call setCustomUserId() immediately after the user successfully completes authentication to ensure all subsequent events are associated with their user ID.

function handleUserLogin(email, password) {
  // Your authentication logic
  authenticateUser(email, password)
    .then(function(response) {
      if (response.success) {
        // Set the user ID in Singular after successful login
        cordova.plugins.SingularCordovaSdk.setCustomUserId(response.userId);
        
        console.log('User ID set:', response.userId);
        
        // Navigate to home screen
        navigateToHome();
      }
    })
    .catch(function(error) {
      console.error('Login failed:', error);
    });
}

Unset Custom User ID

Clear the user ID when a user logs out to ensure accurate session tracking for multi-user devices. This prevents subsequent events from being incorrectly attributed to the logged-out user.

// Unset the user ID on logout
cordova.plugins.SingularCordovaSdk.unsetCustomUserId();

Method Signature:

unsetCustomUserId(): void

Example: Unset User ID on Logout

Call unsetCustomUserId() during the logout flow to clear the user ID and prevent incorrect attribution of subsequent events.

function handleUserLogout() {
  // Clear app data and user session
  clearUserSession()
    .then(function() {
      // Unset the user ID in Singular
      cordova.plugins.SingularCordovaSdk.unsetCustomUserId();
      
      console.log('User ID cleared');
      
      // Navigate to login screen
      navigateToLogin();
    })
    .catch(function(error) {
      console.error('Logout failed:', error);
    });
}

Set User ID During Initialization

If the user ID is available when the app launches (e.g., user is already logged in with persistent session), configure it during SDK initialization using withCustomUserId(). This ensures the first session includes the user ID.

document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  // Check if user is already logged in (e.g., from local storage)
  var userId = localStorage.getItem('user_id');
  
  // Create configuration
  var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    'YOUR_SDK_KEY',
    'YOUR_SDK_SECRET'
  );
  
  // If user ID exists, set it during initialization
  if (userId) {
    config.withCustomUserId(userId);
  }
  
  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(config);
  console.log('Singular SDK initialized');
}

Configuration Method Signature:

withCustomUserId(customUserId: string): SingularConfig