Manage Custom User Data - Kotlin SDK

Prerequisites

To use custom user data, you must have an App Services App with custom user data enabled.

To set up an App Services App that uses custom user data, refer to the following:

1. Connect your app to Atlas App Services

2. Enable Custom User Data in the App Services documentation

Read Custom User Data

You can retrieve custom user data of a currently logged-in user using the User.customDataAsBsonDocument() extension function:

val user = app.currentUser!!
val customUserData = user.customDataAsBsonDocument()

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 or when you explicitly call the User.refreshCustomData() function to request the latest version of a user's custom data.

// Update the custom data object
user.refreshCustomData()
// Now when you access the custom data, it's the
// updated data object
val updatedUserData = user.customDataAsBsonDocument()

Write Custom User Data with 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 Kotlin SDK.

Currently, it is not possible to write to custom user data directly from the Realm Kotlin SDK.

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 and 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 Kotlin SDK code to call this Function:

// Write the custom user data through a call
// to the `writeCustomUserData` function
val functionResponse = user.functions
    .call<BsonDocument>("writeCustomUserData",
        mapOf("userId" to user.id, "favoriteColor" to "blue")
    )
// Refreshed custom user data contains updated
// `favoriteColor` value added in above Atlas Function call
user.refreshCustomData()
val updatedUserData = user.customDataAsBsonDocument()

Delete Custom Data with Atlas Functions

Custom user data is stored in a document linked to the User object.

To delete custom user data, you must manually delete the user's custom data document.

You can delete custom user data using an Atlas Function. Currently, it is not possible to delete custom user data directly from the Realm Kotlin SDK.

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.

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

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

val deleteResponse = user.functions
    .call<BsonDocument>("deleteCustomUserData")