User Profiles

A user in Moesif is an end consumer of your API. If you are an API provider, this may be the individual third-party developer consuming your API or the users that are employees of your customer.

What are user properties?

Users can track various properties such as email, first_name, last_name, etc. For a complete list of properties, check out the User API Reference

A user profile in Moesif

You can customize a user profile and the fields shown. To see exactly how to do this, check out the docs on Profile View

Identification of users

Users in Moesif are identified by a single user_id and potentially associated with many session_token.’s.

  • A user_id is a permanent and unique identifier to track a user across platforms and services. Setting the Moesif user_id field with the id used in your own databases and services is recommended.

  • A session_token is a temporary or semi-permanent token that is associated with the user’s session. Examples include JSON Web Tokens (JWT), API keys, Access Tokens, and session ids.

How to track users

1. Set the identifyUser function

By defining an identifyUser callback such as setting the moesif-nodejs identifyUser() option, you ensure new API calls are associated with a specific user_id.

2. Enrich the user with additional metadata

If you only did Step 1, you’ll see some user analytics in Moesif like first and last seen time, but it’s much more useful if you enrich with your own metadata such as email, first and last name, employment title, social media handles, or any other metadata you want to store in Moesif.

To add user metadata to Moesif, just call the SDK’s updateUser() method from your code, such as the moesif-nodejs updateUser() method with the user_id and JSON metadata you want to store. You only need to call this when your own user data changes, such as when you pull from Clearbit or another data provider.

The update user endpoint

The update user endpoint will perform an upsert if the user_id doesn’t exist, meaning a new user will be created.

You can call the updateUser() directly from the Moesif SDK you already integrated. If you’re calling from a separate service and don’t need the full middleware, you can use one of the Moesif base API libs or REST API directly.

If you attempt to update a user and the user_id doesn’t exist, a new user will be created (i.e., upsert).

The update user API is accessible through the Server SDK or the base API Libs.

Calling either function are equivalent. For example:

  1. Server SDK such as moesif-nodejs’s updateUser() wrapper function.
  2. Base API Lib such as moesifapi-nodejs to call updateUser()(https://www.moesif.com/docs/api?javascript–nodejs#update-a-user) directly.

How to alias a session

Multiple sessions can be associated to the same user profile. That is, the same user_id will be linked to multiple session_token’s.

To create a new link or alias, call the update user API with at least the user_id and session_token set. The new session_token will be appended to the existing user’s alias table.

For example, if you authorize a user by a JSON web token that expires after two weeks.

User metadata

You can save any custom metadata with a user such as the user’s email or employment title. You can search and filter by users in the Moesif portal via the metadata. The metadata must be a valid JSON object.

{
  "is_email_verified": true,
  "facebook_id": "123456789",
  "email": "amy@gmail.com",
  "phone": "123-456-7890",
  "first_name": "Amy",
  "last_name": "Doe",
  "custom_int_field": 55,
  "custom_obj_field": {
    "sub_a": "value_a",
    "sub_b": "value_b"
  }
}

The user metadata can be views in Moesif under a user’s profile. The metadata can be viewed by going to a user profile, clicking the More Actions button, and selecting Show JSON Data.

More Actions button

The data will then be displayed in a modal to view.

Events views

The same rules that apply to API Call metadata also apply to user metadata.

1. Maintain consistent data types

Once a JSON key is seen by Moesif with a specific JSON datatype, you cannot send a different JSON datatype using the same key. For example, if you previously sent to Moesif the following custom metadata for an API call:

{
  "first_name": "John Doe",
  "email": "john@gmail.com",
  "phone": "123-456-7890"
}

Then, Moesif automatically saves phone as a JSON string in the metadata schema. You cannot later send a JSON Number using the same phone key. This is true regardless of the number of levels relative to the object root. The below metadata would now be invalid:

{
  "first_name": "John Doe",
  "email": "john@gmail.com",
  "additional_info": {
    "phone": 1234567890
  }
}

The metadata schema is shared across your organization and applications.

2. Avoid dots characters

Be aware that Dot characters in a JSON key for custom metadata will be converted into an underscore by Moesif automatically. However, Dot characters in a JSON value are fine and will not be transformed.

For example,

{
  "fi.rst.na.me": "John Doe",
  "email": "john@gmail.com",
}

Will be converted by Moesif to:

{
  "fi_rst_na_me": "John Doe",
  "email": "john@gmail.com",
}

Updated: