Skip to Content
AI Powered Docs! 🤖 These docs are translated with AI, so keep an eye out for minor quirks. We're always improving!
Technical DocumentationAndroidTracking Users

User Tracking

The Metrix SDK provides comprehensive user identification and attribute management capabilities. Users can be identified through custom IDs and enriched with various demographic and custom attributes.

Identifying Users to Metrix

To identify a user to the Metrix system and create or update their user profile, call the following methods. This creates or updates a User in Metrix’s database, which can be accessed through the Metrix panel’s User Lookup section.

Setting a Custom User ID

Call this method when a user logs into your application or when you want to associate a custom identifier with the user:

// Call when a user logs into your system
MetrixAnalytics.User.setUserCustomId("userId");
 
// Call when a user logs out of your system
MetrixAnalytics.User.deleteUserCustomId();

Note: The custom user ID is stored locally and sent with every event, allowing Metrix to track user behavior across sessions.

Updating User Information

User information is updated automatically with a 300ms debounce, allowing batch updates before being sent to Metrix.

Setting Custom Attributes

Set arbitrary custom attributes using key-value pairs. Custom attributes can be of any type (String, Number, Boolean, etc.):

Map<String, Object> attributes = new HashMap<>();
attributes.put("type", "Loyal");
attributes.put("signup_date", "2024-11-20T11:24:03.000Z"); // use ISO 8601 to consider this attribute as s a date
 
MetrixAnalytics.User.setCustomAttribute(attributes);

Tip: Use ISO 8601 format for date attributes (e.g., 2024-11-20T11:24:03.000Z) so Metrix correctly recognizes them as dates in the platform.

Setting Predefined User Attributes

The SDK provides dedicated methods for common user attributes:

// Name
MetrixAnalytics.User.setFirstName("userFirstName");
MetrixAnalytics.User.setLastName("userLastName");
 
// Contact Information
MetrixAnalytics.User.setEmail("email");
MetrixAnalytics.User.setHashedEmail("hashedEmail");  // SHA256 hash
MetrixAnalytics.User.setPhoneNumber("phoneNumber");
MetrixAnalytics.User.setHashedPhoneNumber("hashedPhoneNumber");  // SHA256 hash
 
// Location
MetrixAnalytics.User.setCountry("country");
MetrixAnalytics.User.setRegion("region");
MetrixAnalytics.User.setCity("city");
MetrixAnalytics.User.setLocality("locality");
 
// Demographics
MetrixAnalytics.User.setGender(UserGender.MALE);  // Options: MALE, FEMALE, OTHER
MetrixAnalytics.User.setBirthday(birthday);  // Birthday value type should be 'Long' (timestamp in milliseconds)
 
// Push Notification
MetrixAnalytics.User.setFcmToken("fcm_token_value");
 
// Messaging Channels
MetrixAnalytics.User.channelEnabled(MessageChannel.SMS);
MetrixAnalytics.User.channelEnabled(MessageChannel.EMAIL);
MetrixAnalytics.User.channelDisabled(MessageChannel.SMS);

User Attribute Reference

AttributeTypeDescriptionMethod
customIdStringUnique identifier for the user (email, username, etc.)setUserCustomId() / deleteUserCustomId()
firstNameStringUser’s first namesetFirstName()
lastNameStringUser’s last namesetLastName()
emailStringUser’s email address (plain text)setEmail()
hashedEmailStringUser’s email address (SHA256 hashed)setHashedEmail()
phoneNumberStringUser’s phone number (plain text)setPhoneNumber()
hashedPhoneNumberStringUser’s phone number (SHA256 hashed)setHashedPhoneNumber()
countryStringUser’s countrysetCountry()
regionStringUser’s region/state/provincesetRegion()
cityStringUser’s citysetCity()
localityStringUser’s locality/neighborhoodsetLocality()
genderUserGenderUser’s gender (MALE, FEMALE, OTHER)setGender()
birthdayLongUser’s birth date (timestamp in milliseconds)setBirthday()
fcmTokenStringFCM registration token for push notificationssetFcmToken()
customAttributesMapCustom key-value pairs for user datasetCustomAttribute() / setUserAttributes()
channelsSetEnabled messaging channels (SMS, PUSH, EMAIL)channelEnabled() / channelDisabled()

Messaging Channels

Manage which communication channels are enabled for the user:

// Available channels: SMS, PUSH, EMAIL
 
// Enable a channel
MetrixAnalytics.User.channelEnabled(MessageChannel.SMS);
MetrixAnalytics.User.channelEnabled(MessageChannel.PUSH);
MetrixAnalytics.User.channelEnabled(MessageChannel.EMAIL);
 
// Disable a channel
MetrixAnalytics.User.channelDisabled(MessageChannel.SMS);

Best Practices

Call After Authentication

Always set the user ID after successful user authentication or login:

// After successful login
User user = authenticateUser(username, password);
if (user != null) {
    MetrixAnalytics.User.setUserCustomId(user.getId());
    MetrixAnalytics.User.setEmail(user.getEmail());
    MetrixAnalytics.User.setFirstName(user.getFirstName());
}

Use Consistent Identifiers

Use the same user ID format consistently across all app sessions:

// Good: Use email consistently
MetrixAnalytics.User.setUserCustomId(user.getEmail());
 
// Bad: Changing between user ID and email
MetrixAnalytics.User.setUserCustomId(user.getId());  // Session 1
MetrixAnalytics.User.setUserCustomId(user.getEmail());  // Session 2

Hash Sensitive Data

Hash email and phone numbers using SHA256 before sending:

import java.security.MessageDigest;
 
public static String sha256Hash(String input) {
    try {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(input.getBytes());
        StringBuilder hexString = new StringBuilder();
        for (byte b : hash) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }
        return hexString.toString();
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}
 
// Usage
MetrixAnalytics.User.setHashedEmail(sha256Hash("user@example.com"));
MetrixAnalytics.User.setHashedPhoneNumber(sha256Hash("989123456789"));

Batch Updates

Updates are automatically debounced (300ms), so you can batch multiple attribute updates without performance concerns:

// All these calls are batched into a single update
MetrixAnalytics.User.setFirstName("John");
MetrixAnalytics.User.setLastName("Doe");
MetrixAnalytics.User.setEmail("john@example.com");
MetrixAnalytics.User.setPhoneNumber("989123456789");
MetrixAnalytics.User.setCountry("Iran");

Attribute Limits

  • Maximum custom attributes: up to 50 per event
  • Maximum key length: 512 bytes
  • Maximum value length: 512 bytes

Clear on Logout

Always clear the user ID when a user logs out:

// When user logs out
MetrixAnalytics.User.deleteUserCustomId();

User ID Listeners

Listen for user ID changes from external sources (e.g., device-level identifier acquisition):

MetrixAnalytics.setUserIdListener(userId -> {
    Log.d("Analytics", "User ID received: " + userId);
    // Update your UI or perform other actions
});
Getting StartedTracking Events