Guides
Guides

Set User Identity & Properties

📱

On a different platform? iOS · React Native · Flutter · Cordova · NativeScript · Xamarin MAUI

Identify Users Reliably with setUserIdentity

UXCam gives every fresh install a random alias name based on unique Install ID.

That works... until issues arise, such as when the same person re-installs the app, shares a device with another user, or signs into their account on multiple devices (which creates a different Install ID for each).

Fix: call UXCam.setUserIdentity()once per session as soon as the real user is known (login, sign‑up, deep‑link token, silent auth).

When to call setUserIdentity

TriggerWhy it works
Immediately after successful login / sign‑upBackend‑verified identifier—safe to map to the Install ID.
Every app launch (recommended, idempotent)Catches silent or SSO (Single Sign-On) logins and reinstalls; the call is debounced to prevent unnecessary repeated calls.

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

Success

Negative potential consequences of an action.


Code snippet

// After the auth flow succeeds
String uid = authResult.getUserId();      // e.g. "user_42"
UXCam.setUserIdentity(uid);
UXCam.setUserIdentity(authResult.userId)

Enrich Users with Custom Properties

Attach up to 100 key–value pairs per user to segment funnels and heat‑maps by plan, cohort, geography, and more.

UXCam.setUserProperty("plan",            "pro");
UXCam.setUserProperty("signup_source",   "google_ads");
UXCam.setUserProperty("nps_score",       "9");  // Cast numbers to strings
Best-practiceWhy
Use stable, non‑PII IDs / enumsAvoid GDPR headaches; you can always map to an email in your own DB.
Prefer snake_case keysPrevents duplicates (planType vs plan_type).
Update only when a value changesThe SDK overwrites the previous value—no need to resend unchanged props.
🚧

Need to send PII (e.g. email)? Sign a DPA with UXCam first: [email protected].

Verify Your Work

  1. Log in with a test account on a debug build.
  2. Wait for the session to upload.
  3. In the Dashboard, open Users → Search and enter the test User ID.
  4. You should see one merged user with sessions from all devices and reinstalls.

If the user is missing:

  • Check Logcat for UXCam: setUserIdentity called with ....
  • Ensure the call runs after the SDK has been initialized with UXCam.startWithConfiguration().
  • Confirm the ID is non‑null & non‑empty (empty strings are ignored).

Troubleshooting Cheat‑Sheet

IssueLikely causeFix
Two records for the same userDifferent casing (User42 vs user42)Convert IDs to lower‑case before sending.
User disappears after reinstallsetUserIdentity only called on first installAlso call it on every app launch or after silent token refresh.
Property not visibleSent as int; dashboard expects stringsCast all numeric values to strings.

QA Checklist

  • UXCam.setUserIdentity() is called once per session after authentication.
  • Key properties (plan, signup_source, …) appear under user properties.
  • No PII stored unless a DPA is in place.
  • Re-installing the app and logging in links the new session to the correct user.

Updated 5 days ago