Navigation

Access Custom User Data

Overview

You can read arbitrary data about your application users, known as custom user data, directly within your web application. For example, you might store a user’s preferred language, date of birth, or local timezone.

Realm references a MongoDB collection in your linked cluster to find the custom data for a given user but does not add or update any custom user data documents. You are responsible for managing and updating user data in the collection. For details on how to enable and configure custom user data, see Enable Custom User Data

Example User Object

The code examples in this page use the following user object on which the custom_data field has not yet been set.

{
  id: '5f1f216e82df4a7979f9da93',
  type: 'normal',
  data: { email: 'test@example.com' },
  custom_data: {
    _id: '5f20d083a37057d55edbdd57',
    userID: '5f1f216e82df4a7979f9da93',
    description: 'a test document for user: test@example.com',
  },
  identities: [
    { id: '5f1f216e82df4a7979f9da90', provider_type: 'local-userpass' }
  ]
}

Note

To use custom user data, you must Enable Custom User Data.

Read Custom User Data

Custom Data May Be Stale

MongoDB Realm does not dynamically update a user’s custom data if the underlying document changes. Instead, MongoDB Realm fetches a new copy of the data whenever a user refreshes their access token, such as when they log in. This may mean that the custom data won’t immediately reflect changes, e.g. updates from an authentication Trigger. The client SDKs automatically refresh a logged-in user’s access token periodically, so the user’s custom data should never remain stale for more than 30 minutes.

You can access a read-only copy of a logged in user’s custom data directly from the Realm.User.customData property.

// Access a logged in user's read-only custom data
const customData = app.currentUser.customData
console.log(customData);

To manually fetch the latest version of a user’s custom data, call User.refreshCustomData().

// Refresh a user's custom data to make sure we have the latest version
await app.currentUser.refreshCustomData();

Output

{
  "_id": "5f233a3ac49aca916792de1d",
  "description": "a test document for user test@example.com",
  "userID": "5f1f298f757611faec901d0f",
  "favoriteColor": "pink"
}

Modify a User’s Custom Data

Note

To modify the custom data field from a client or user function, write permission to the collection in which custom data is stored must be configured. If you prefer to restrict client write access to custom data from your application, you can still modify the object from a system function.

You can modify a user’s custom data by updating the underlying document in your app’s custom data collection.

The following example updates the user’s custom data to set the favoriteColor property to "purple":

// Get a client object for your app's custom user data collection
const mongodb = app.services.mongodb("<MongoDB Service Name>");
const collection = mongo.db("<Database Name>").collection("<Collection Name>");

// Log the user's favorite color before we change it
console.log("old favoriteColor: ", app.currentUser.customData.favoriteColor);

// Update the user's custom data document
await collection.updateOne(
  { userID: app.currentUser.id }, // Query for the user object of the logged in user
  { $set: { favoriteColor: "purple" } } // Set the logged in user's favorite color to purple
);
// Refresh the user's local customData property
await app.currentUser.refreshCustomData();

// Log the user's new favorite color
console.log("new favoriteColor: ", app.currentUser.customData.favoriteColor);

Output

old favoriteColor: pink
new favoriteColor: purple

Summary

  • You can use custom user data to store information about your application users.
  • The custom user data field of the user object is read-only, and can only be modified to by performing CRUD operations through the Atlas service.