user-metadata.txt

.. meta::
   :robots: noindex, nosnippet

.. _kotlin-user-metadata:

=================================
Manage User Metadata - Kotlin SDK
=================================

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

This page describes how to manage user metadata for an authorized App 
Services App user using the Realm Kotlin SDK. For more information, 
refer to :ref:`<auth-provider-metadata>` in the App Services documentation.

Atlas App Services can read **user metadata** from authentication providers. 
Then, App Services exposes each user's 
data in a field of their ``User`` object. For example, you might want to 
access a user's name, email, birthday, or gender.

.. _kotlin-read-user-metadata:

Read a User's Metadata
----------------------

You can read the user metadata of a currently logged-in user through 
that user's 
`User <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb/-user/index.html>`__ 
object. You cannot edit user metadata through a ``User`` object. 

To read the data, call the 
`profileAsBsonDocument <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.ext/profile-as-bson-document.html>`__ 
method on the ``User`` object of a logged-in user:

.. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.get-user-metadata.kt
   :language: kotlin

User metadata options vary depending on which provider you're using and
:ref:`which metadata fields you enable <configure-user-metadata-on-the-backend>`.

.. include:: /includes/stale-user-metadata.rst

Serializable User Metadata 
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.9.0

Kotlin SDK version 1.9.0 introduced an API that supports: 

- A limited but stable EJSON encoder for user metadata returned by ``User.profileAsBsonDocument()``
- An experimental EJSON encoder that supports full document serialization for user 
  metadata returned by the `User.profile() <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.ext/profile.html>`__ 
  extension method. This encoder and method requires experimental opt-in. 

You must add the official
`Kotlin Serialization <https://github.com/Kotlin/kotlinx.serialization>`__ library
to your project to use Realm Kotlin SDK's EJSON serialization.
For more information, refer to 
:ref:`Serialization <kotlin-serialization>`. 

.. _kotlin-configure-user-metadata:

Configure User Metadata
-----------------------

.. include:: /includes/configure-user-metadata.rst

.. _kotlin-update-user-metadata:

Update User Metadata
--------------------

.. include:: /includes/update-user-metadata.rst