diff --git a/source/includes/api-details/csharp/users/user-metadata-read-user-metadata-description.rst b/source/includes/api-details/csharp/users/user-metadata-read-user-metadata-description.rst new file mode 100644 index 0000000000..9d83686b25 --- /dev/null +++ b/source/includes/api-details/csharp/users/user-metadata-read-user-metadata-description.rst @@ -0,0 +1,8 @@ +You can read the user metadata of a currently logged-in user through the +:dotnet-sdk:`User ` object. + +The ``Profile`` property on the ``User`` object returns a +:dotnet-sdk:`UserProfile ` object +of a logged-in user. + +The following example shows how to get a user's email from the metadata. diff --git a/source/includes/api-details/dart/users/user-metadata-read-user-metadata-description.rst b/source/includes/api-details/dart/users/user-metadata-read-user-metadata-description.rst new file mode 100644 index 0000000000..d099000529 --- /dev/null +++ b/source/includes/api-details/dart/users/user-metadata-read-user-metadata-description.rst @@ -0,0 +1,8 @@ +You can read the user metadata of a currently logged-in user through the +:flutter-sdk:`User ` object. + +The ``profile`` property on the ``User`` object returns a +:flutter-sdk:`User.profile ` object +of a logged-in user. + +The following example shows how to get a user's email from the metatdata. diff --git a/source/includes/api-details/generic/users/user-metadata-serializable-user-metadata-not-supported.rst b/source/includes/api-details/generic/users/user-metadata-serializable-user-metadata-not-supported.rst new file mode 100644 index 0000000000..36ce6c7510 --- /dev/null +++ b/source/includes/api-details/generic/users/user-metadata-serializable-user-metadata-not-supported.rst @@ -0,0 +1,2 @@ +The selected language does not provide serializable user metadata. This +functionality is only available in Kotlin. diff --git a/source/includes/api-details/javascript/users/user-metadata-read-user-metadata-js-ts-description.rst b/source/includes/api-details/javascript/users/user-metadata-read-user-metadata-js-ts-description.rst new file mode 100644 index 0000000000..73998c771c --- /dev/null +++ b/source/includes/api-details/javascript/users/user-metadata-read-user-metadata-js-ts-description.rst @@ -0,0 +1,5 @@ +You can read the user metadata of a currently logged-in user through that +user's ``User`` object. + +To read the data, access the ``profile`` property on the ``User`` object +of a logged-in user. diff --git a/source/includes/api-details/kotlin/users/user-metadata-read-user-metadata-description.rst b/source/includes/api-details/kotlin/users/user-metadata-read-user-metadata-description.rst new file mode 100644 index 0000000000..bba823aa8d --- /dev/null +++ b/source/includes/api-details/kotlin/users/user-metadata-read-user-metadata-description.rst @@ -0,0 +1,8 @@ +You can read the user metadata of a currently logged-in user through +that user's +:kotlin-sync-sdk:`User ` +object. You cannot edit user metadata through a ``User`` object. + +To read the data, call the :kotlin-sync-sdk:`profileAsBsonDocument +` +method on the ``User`` object of a logged-in user. diff --git a/source/includes/api-details/kotlin/users/user-metadata-serializable-user-metadata-description.rst b/source/includes/api-details/kotlin/users/user-metadata-serializable-user-metadata-description.rst new file mode 100644 index 0000000000..c4c44ea8ae --- /dev/null +++ b/source/includes/api-details/kotlin/users/user-metadata-serializable-user-metadata-description.rst @@ -0,0 +1,14 @@ +.. 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 :kotlin-sync-sdk:`User.profile() + ` extension method. This encoder + and method requires experimental opt-in. + +You must add the official +`Kotlin Serialization `__ +library to your project to use the Kotlin SDK's EJSON serialization. +For more information, refer to :ref:`Serialization `. diff --git a/source/includes/api-details/swift/users/user-metadata-read-user-metadata-description.rst b/source/includes/api-details/swift/users/user-metadata-read-user-metadata-description.rst new file mode 100644 index 0000000000..8effdfae3c --- /dev/null +++ b/source/includes/api-details/swift/users/user-metadata-read-user-metadata-description.rst @@ -0,0 +1,5 @@ +You can read the user metadata of a currently logged-in user through that +user's ``User`` object. + +To read the data, access the ``profile`` property on the ``User`` object +of a logged-in user. diff --git a/source/includes/configure-user-metadata.rst b/source/includes/configure-user-metadata.rst deleted file mode 100644 index 2d55693d65..0000000000 --- a/source/includes/configure-user-metadata.rst +++ /dev/null @@ -1,13 +0,0 @@ -You can only read user metadata from the client app that you have configured -on the App Services application. - -You can configure the :ref:`user metadata ` you request from -an authentication provider. You do this directly on the authentication -provider's configuration. For more details on which metadata fields you -can use, see the provider details: - -- OAuth 2.0 (:ref:`Facebook ` & :ref:`Google `) -- :ref:`Custom JWT ` - -You can change which metadata fields you have configured by :ref:`editing the -provider's configuration `. \ No newline at end of file diff --git a/source/includes/sdk-examples/users/user-metadata-read-user-metadata.rst b/source/includes/sdk-examples/users/user-metadata-read-user-metadata.rst new file mode 100644 index 0000000000..b682e10987 --- /dev/null +++ b/source/includes/sdk-examples/users/user-metadata-read-user-metadata.rst @@ -0,0 +1,38 @@ +.. tabs-drivers:: + + tabs: + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/UserLinkExamples.snippet.user-metadata.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.user-metadata.dart + :language: dart + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.user-metadata.js + :language: js + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.get-user-metadata.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.read-user-metadata.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.user-metadata.js + :language: js diff --git a/source/includes/update-user-metadata.rst b/source/includes/update-user-metadata.rst deleted file mode 100644 index 5120d06a0e..0000000000 --- a/source/includes/update-user-metadata.rst +++ /dev/null @@ -1,6 +0,0 @@ -User metadata that you access through the authentication provider is read-only -data. You cannot update or edit user metadata that comes from this source. - -If you would like to give a user the option the update their metadata from -within your client app, use :ref:`custom user data `, -instead. \ No newline at end of file diff --git a/source/sdk/users/user-metadata.txt b/source/sdk/users/user-metadata.txt index 0d36c57fce..2f1f95d641 100644 --- a/source/sdk/users/user-metadata.txt +++ b/source/sdk/users/user-metadata.txt @@ -4,10 +4,125 @@ User Metadata ============= +.. meta:: + :description: Use Atlas Device SDK to read user metadata, such as email or birthday, from configured authentication providers. + :keywords: Realm, Flutter SDK, Kotlin SDK, .NET SDK, Node.js SDK, Swift SDK, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: csharp, dart, javascript/typescript, kotlin, swift + .. contents:: On this page :local: :backlinks: none :depth: 2 :class: singlecol -Placeholder page for user metadata content. +.. tabs-selector:: drivers + +This page describes how to manage user metadata for an authorized App +Services App user using Atlas Device 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, +such as Google or Facebook. Then, App Services exposes each user's metadata in +a field of their ``User`` object. For example, you might want to access a +user's name, email, birthday, or gender. This is read-only data that comes +from the third-party authentication provider. + +This is distinct from maintaining your own, editable custom user data. If +you'd like to define your own user data fields, or have the ability to directly +update user data, use :ref:`sdks-custom-user-data`. + +.. important:: Configure Metadata in Atlas + + Before you can work with metadata provided by the authentication provider, + you must :ref:`configure metadata for the authentication provider + `. + +.. _sdks-read-user-metadata: + +Read User Metadata +------------------ + +.. tabs-drivers:: + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/users/user-metadata-read-user-metadata-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/user-metadata-read-user-metadata-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/user-metadata-read-user-metadata-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/user-metadata-read-user-metadata-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/user-metadata-read-user-metadata-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/user-metadata-read-user-metadata-js-ts-description.rst + +.. include:: /includes/sdk-examples/users/user-metadata-read-user-metadata.rst + +User metadata options vary depending on which provider you're using and +:ref:`which metadata fields you enable `. + +.. include:: /includes/stale-user-metadata.rst + +.. _sdks-serializable-user-metadata: + +Serializable User Metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the SDK languages provide serializers for user metadata. + +.. tabs-drivers:: + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/users/user-metadata-serializable-user-metadata-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/users/user-metadata-serializable-user-metadata-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/users/user-metadata-serializable-user-metadata-not-supported.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/user-metadata-serializable-user-metadata-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/users/user-metadata-serializable-user-metadata-not-supported.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/users/user-metadata-serializable-user-metadata-not-supported.rst