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' } ] }
To use custom user data, you must first Enable Custom User Data.
Read Custom User Data¶
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¶
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.