Custom User Data - Flutter SDK

Before You Begin

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

1. Create an App.

2. Enable custom user data.

Read a User's 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()

Write Custom User Data with an Atlas Functions

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.

exports = async function writeCustomUserData(newCustomUserData) {
  const userId = context.user.id;
  const customUserDataCollection = context.services
    .get("mongodb-atlas")
    .db("custom-user-data-database")
    .collection("custom-user-data");
  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:

final user = app.currentUser!;
final updatedTimestamp = DateTime.now().millisecondsSinceEpoch;
final updatedCustomUserData = {
  "userId": user.id,
  "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();