Docs Menu

Docs HomeDevelop ApplicationsAtlas Device SDK

Custom User Data - C++ SDK

On this page

  • Read a User's Custom Data
  • Create a User's Custom Data Document
  • Update a User's Custom Data
  • Delete a User's Custom Data

You can read the custom user data of a currently logged-in user through that user's User object. You cannot edit custom user data through a User object. To edit custom user data, see Update Custom User Data. To read the data, access the custom_data property on the User object of a logged-in user:

// Custom user data could be stale, so refresh it before reading it
user.refresh_custom_user_data().get();
auto userData = user.custom_data().value();
/* Parse the string custom data to use it more easily in your code.
In this example, we're using the nlohmann/json library, but use whatever
works with your application's constraints. */
auto userDataObject = nlohmann::json::parse(userData);
CHECK(userDataObject["favoriteColor"] == "gold");

Warning

Custom Data May Be Stale

Atlas App Services does not dynamically update the value of the client-side user custom data document immediately when underlying data changes. Instead, App Services fetches the most recent version of custom user data whenever a user refreshes their access token, which is used by most SDK operations that contact the App Services backend. If the token is not refreshed before its default 30 minute expiration time, the C++ SDK refreshes the token on the next call to the backend. Custom user data could be stale for up to 30 minutes plus the time until the next SDK call to the backend occurs.

Note

If you require the most recent version of custom user data, use the refresh_custom_user_data() function to request the latest version of a user's custom data.

To create custom user data for a user, create a MongoDB document in the custom user data collection. The user ID field of the document should contain the the user's user ID.

Tip

In the App Services UI, check the App Users page under the Custom User Data tab to find and configure custom user data settings, including:

  • The custom user data cluster, database, and collection

  • The user ID field used to map custom user data documents to users

One way you can create this document is by calling an Atlas Function that inserts a custom data document into the custom user data collection. There is no single pattern for adding custom user data from an Atlas Function. You should write your Function or Functions to suit 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.

updateCustomUserData.js - Atlas Function running on server (JavaScript)
exports = async function updateCustomUserData(newCustomUserData) {
const userId = context.user.id;
const customUserDataCollection = context.services
.get("mongodb-atlas")
.db("custom-user-data-database")
.collection("cpp-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 following example calls a function to insert a document containing the user ID of the currently logged in user and a favoriteColor value into the custom user data collection:

auto user = app.login(realm::App::credentials::anonymous()).get();
// Functions take a string argument. Any quotes within the array must be
// escaped.
auto customData =
"[{\"userId\":\"" + user.identifier() + "\",\"favoriteColor\":\"gold\"}]";
// Call an Atlas Function to insert custom data for the user
auto result = user.call_function("updateCustomUserData", customData).get();

You can add any number of arbitrary fields and values to the custom user data document when you create it. The user ID field is the only requirement for the document to become available on the User object as custom user data.

You can update custom user data using an Atlas Function, MongoDB Compass, or the MongoDB Atlas Data Explorer.

To update a user's custom user data with an Atlas Function, edit the MongoDB document whose user ID field contains the user ID of the user. The following example calls the same function used to create the custom user data document above. Here, we update the favoriteColor field of the the document containing the user ID of the currently logged in user:

// Functions take a string argument. Any quotes within the array must be
// escaped.
auto updatedData = "[{\"userId\":\"" + user.identifier() +
"\",\"favoriteColor\":\"black\"}]";
// Call an Atlas Function to update custom data for the user
auto updateResult =
user.call_function("updateCustomUserData", updatedData).get();
// Refresh the custom user data before reading it to verify it succeeded
user.refresh_custom_user_data().get();
auto updatedUserData = user.custom_data().value();
/* Parse the string custom data to use it more easily in your code.
In this example, we're using the nlohmann/json library, but use whatever
works with your application's constraints. */
auto updatedUserDataObject = nlohmann::json::parse(updatedUserData);
CHECK(updatedUserDataObject["favoriteColor"] == "black");

Tip

To determine a user's ID, access the user.identifier() property or find the user in the App Services UI on the App Users page under the Users tab.

Custom user data is stored in a document linked to the user object. Deleting a user does not delete the custom user data. To fully delete user data to comply with, for example, Apple's Account deletion guidance, you must manually delete the user's custom data document.

You can delete custom user data using an Atlas Function, MongoDB Compass, or the MongoDB Atlas Data Explorer.

In this example, the Atlas Function does not require any arguments. The Function uses the function context to determine the caller's user ID, and deletes the custom user data document matching the user's ID.

deleteCustomUserData.js - Atlas Function running on server (JavaScript)
exports = async function deleteCustomUserData() {
const userId = context.user.id;
const customUserDataCollection = context.services
.get("mongodb-atlas")
.db("custom-user-data-database")
.collection("cpp-custom-user-data");
const filter = { userId };
const res = await customUserDataCollection.deleteOne(filter);
return res;
};

The code that calls this function requires only a logged-in user to call the function:

auto deleteResult = user.call_function("deleteCustomUserData", "[]").get();
←  Manage Email/Password Users - C++ SDKSync Data Between Devices - C++ SDK →