Docs Menu
Docs Home
/ /
Atlas Device SDKs
/ /

Manage Custom User Data - Kotlin SDK

On this page

  • Prerequisites
  • Read Custom User Data
  • Write Custom User Data with Atlas Functions
  • Delete Custom Data with Atlas Functions

This page describes custom user data in an App Services App and how to manage it with the Realm Kotlin SDK.

Important

Currently you can only read custom user data with the Kotlin 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.

Atlas App Services lets you associate data with an authenticated user, such as a user's preferred language, date of birth, or local timezone. You can store this arbitrary custom user data about your users and read it from your client application.

New in version 1.9.0.

You can serialize custom user data using an EJSON encoder. For more information, including examples, refer to EJSON Encoding for Atlas.

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

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()

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.

writeCustomUserData.js - Atlas Function running on server (JavaScript)
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()

Note

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

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

Important

Deleting a user does not delete the custom user data. You might need to fully delete user data to ensure legal compliance (for example, to comply with Apple's account deletion requirements).

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.

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("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")

Back

Delete Users

Next

Manage User Metadata