- Stitch >
- Users & Authentication >
- User Management
Configure Custom User Data¶
Overview¶
You can store arbitrary data about your application users in a MongoDB collection and configure Stitch to automatically expose each user’s data in a field of their user object. For example, you might store a user’s preferred language, date of birth, or their local timezone.
Stitch automatically finds a user’s custom data document and includes it
in their access token when they log in. You can access the data in the
custom_data
field of the user’s object in function context, the %%user
expansion,
and their client application access token.
Stitch does not manage custom user documents so you are responsible for
creating and deleting them. The underlying data is a regular MongoDB
document, so you can use standard CRUD operations through the
MongoDB Atlas service to define and modify a user’s
custom data. You can also use authentication triggers to dynamically update user
documents, such as storing the time of their most recent login in the
lastLogin
field.
Example
You can access custom user data in the client SDKs as well as functions and rule expressions.
- Functions
- Json Expressions
- JavaScript SDK
- Android SDK
- iOS SDK
Store One Document Per User
Documents that contain user data must contain the user’s ID in a specific field. If multiple documents specify the same user’s ID, Stitch only exposes the data from the document that was inserted first.
Custom Data May Be Stale
Stitch does not dynamically update a user’s custom data if the underlying document changes. Instead, Stitch fetches a new copy of the data whenever a user refreshes their access token, such as when they log in. This may mean that the custom data won’t immediately reflect changes, e.g. updates from an authentication trigger. The client SDKs automatically refresh a user’s access token periodically when they’re logged in, so the user’s custom data should not be stale for more than 30 minutes.
Procedure¶
- Stitch UI
- Import/Export
Enable Custom User Data¶
To configure Stitch to associate data in a collection with your application’s users, set the Enable Custom User Data toggle to On.
Specify the Custom User Data Collection¶
You must store the custom data for your application’s users in a single collection of a linked MongoDB Atlas cluster. To configure your application to read user data from this collection, you need to specify the following values:
- Cluster Name: The name of a linked MongoDB cluster that contains the custom user data collection.
- Database Name: The name of the MongoDB database that contains the custom user data collection.
- Collection Name: The name of the MongoDB collection that contains custom user data.
Specify the User ID Field¶
Every document in the custom user data collection should have a field that contains the user ID of the Stitch user that it describes. Specify the name of the field that contains each user’s ID in the User ID Field input.
Deploy the Updated Application¶
Once you have configured the customer user data collection, you can make custom user data available to client applications by deploying your application. To deploy a draft application from the Stitch UI:
- Click Deploy in the left-hand navigation
- Find the draft in the deployment history table and then click Review & Deploy Changes.
- Review the diff of changes and then click Deploy.
Once the application successfully deploys, Stitch begins to associate
custom data with users. When a user logs in, Stitch automatically
queries the custom user data collection for a document where the
specified User ID Field contains the user’s ID. If a
document matches, Stitch exposes the data in the document in the
custom_data
field of that user’s user object.
Export Your Stitch Application¶
You can set up and enable custom user data through Stitch CLI or automatic GitHub deployment. To configure custom user data, you need the latest version of the application directory for your application.
You can export your application from the Export tab of the Settings page in the Stitch UI, or by running the following command from an authenticated instance of stitch-cli:
Configure Custom User Data¶
You must store the custom data for your application’s users in a single collection of a linked MongoDB Atlas cluster. Every document in the collection should have a field that contains the Stitch user ID of the user it describes.
To configure your application to read user data from this collection,
specify a configuration document in the custom_user_data_config
field of stitch.json
:
Field | Description |
---|---|
enabled |
A boolean that, if true , indicates that Stitch should
associate data in the specified collection with application
users. |
mongo_service_id |
The service ID of the linked MongoDB cluster that contains the custom user data collection. |
database_name |
The name of the MongoDB database that contains the custom user data collection. |
collection_name |
The name of the MongoDB collection that contains custom user data. |
user_id_field |
The name of a field that contains an application user’s ID value. All user documents in the collection must have this field and no two documents may contain the same user ID. |
Deploy the Updated Application¶
Once you have configured the customer user data collection, you can make custom user data available to client applications by deploying your application.
To deploy a draft application with Stitch CLI:
To deploy a draft application with automatic GitHub deployment:
Once the application successfully deploys, Stitch begins to associate
custom data with users. When a user logs in, Stitch automatically
queries the custom user data collection for a document where the
specified User ID Field contains the user’s ID. If a
document matches, Stitch exposes the data in the document in the
custom_data
field of that user’s user object.