Access Custom User Data - Web SDK

On this page

Overview

Example User Object
Read Custom User Data
Output
Modify a User's Custom Data
Output
Summary

Atlas Device SDKs are deprecated. Refer to the deprecation page for details.

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' }
  ]
}

Important

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

Read Custom User Data

Warning

Custom Data May Be Stale

App Services does not dynamically update a user's custom data if the underlying document changes. Instead, App Services 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. If the token is not refreshed, the SDK waits 30 minutes and then refreshes it on the next call to the backend, so custom user data could be stale for up to 30 minutes plus the time until the next SDK call to the backend occurs.

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;

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 mongo = app.currentUser.mongoClient(CLUSTER_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.

Back

Work with Multiple Users

Link User Identities