Docs Menu
Docs Home
/ /
Atlas Device SDKs
/ /

Custom User Data - Flutter SDK

On this page

  • Before You Begin
  • Read a User's Custom User Data
  • Write Custom User Data with an Atlas Functions

You can store arbitrary custom data about your users with Atlas App Services. For example, you might store a user's preferred language, date of birth, or local timezone. Before writing and reading this data, you must enable custom user data in the backend. To learn more, see Enable Custom User Data.


Currently you can only read custom user data with the Flutter SDK. In a future update to the SDK, you will be able to write custom user data from the SDK as well.

You can create, update, or delete custom user data using one of the other Realm SDKs, with Atlas Functions, or by directly querying Atlas.

To use custom user data, you must first enable custom user data in App Services:

  1. Create an App.

  2. Enable custom user data.

You retrieve custom user data in the User.customData property of a logged in user:

final customUserData = user.customData;

App Services does not dynamically update the value of the User.customData immediately when underlying data changes. Instead, App Services fetches the most recent version of custom user data whenever a user refreshes their access token or when you explicitly call User.refreshCustomData(), which ensures your app has the latest custom user data.

// refreshCustomData() returns the updated custom data object
final updatedCustomData = await user.refreshCustomData();
// Now when you access User.customData it's the value
// returned from User.refreshCustomData()

You can write to custom user data with an Atlas Function. Atlas Functions are server-side JavaScript functions that are built into your backend App. You can call an Atlas Function directly from the Realm Flutter SDK.

It is not possible to write to custom user data directly from the Realm Flutter SDK.

To learn more about Atlas Functions, refer to the following documentation:

  • Call an Atlas Function

  • Atlas Functions in the App Services documentation.

There is no single pattern for adding custom user data from an Atlas Function. You should write your Function or Functions to suite your application's use case.

In this example, the Atlas Function takes an object passed by the client add adds it to the custom user data collection in Atlas. The Function creates the custom user data if it doesn't already exist and replaces all data in it if it does exist.

writeCustomUserData.js - Atlas Function running on server (JavaScript)
exports = async function writeCustomUserData(newCustomUserData) {
const userId =;
const customUserDataCollection =
const filter = { userId };
// Replace the existing custom user data document with the new one.
const update = { $set: newCustomUserData };
// Insert document if it doesn't already exist
const options = { upsert: true };
const res = await customUserDataCollection.updateOne(filter, update, options);
return res;

The Realm SDK code to call this Function:

Realm Flutter SDK client code (Dart)
final user = app.currentUser!;
final updatedTimestamp =;
final updatedCustomUserData = {
"favoriteFood": "pizza",
"lastUpdated": updatedTimestamp
final functionResponse = await user.functions
.call("writeCustomUserData", [updatedCustomUserData]);
// Contains the `updatedCustomUserData` object just added
// in the above Atlas Function call
final customUserData = await user.refreshCustomData();


Link User Identities


User Metadata