(DOCSP-39528): Consolidate User Metadata page (#3344)

dacharyc · web-flow · commit 3c38bc1f45b5 · 2024-08-16T15:13:25.000-04:00
## Pull Request Info - SDK Docs Consolidation Jira ticket: https://jira.mongodb.org/browse/DOCSP-39528 *Staged Page* - [User Metadata](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-39528/sdk/users/user-metadata/) *Page Source* Add links to every SDK's pages where you got the SDK-specific information: - [Flutter: User Metadata](https://www.mongodb.com/docs/atlas/device-sdks/sdk/flutter/users/user-metadata/) - [Kotlin: Manage User Metadata](https://www.mongodb.com/docs/atlas/device-sdks/sdk/kotlin/users/user-metadata/) - [.NET: User Metadata](https://www.mongodb.com/docs/atlas/device-sdks/sdk/dotnet/manage-users/user-metadata/) - [Node.js: User Metadata](https://www.mongodb.com/docs/atlas/device-sdks/sdk/node/users/user-metadata/) - [Swift: User Metadata](https://www.mongodb.com/docs/atlas/device-sdks/sdk/swift/users/user-metadata/) ### PR Author Checklist Before requesting a review for your PR, please check these items: - [x] Open the PR against the `feature-consolidated-sdk-docs` branch instead of `master` - [x] Tag the consolidated page for: - genre - meta.keywords - meta.description #### Naming - [x] Update Realm naming and the language around persistence layer/local/device per [this document](https://docs.google.com/document/d/126OczVxBWAwZ4P5ZsSM29WI3REvONEr1ald-mAwPtyQ/edit?usp=sharing) - [x] Include `.rst` files comply with [the naming guidelines](https://docs.google.com/document/d/1h8cr66zoEVeXytVfvDxlCSsUS5IZwvUQvfSCEXNMpek/edit#heading=h.ulh8b5f2hu9) #### Links and Refs - [x] Create new consolidated SDK ref targets starting with "_sdks-" for relevant sections - [x] Remove or update any SDK-specific refs to use the new consolidated SDK ref targets - [x] [Update any Kotlin API links](https://jira.mongodb.org/browse/DOCSP-32519) to use the new Kotlin SDK roles #### Content - [x] Shared code boxes have snippets or placeholders for all 9 languages - [x] API description sections have API details or a generic placeholder for all 9 languages - [x] Check related pages for relevant content to include - [x] Create a ticket for missing examples in each relevant SDK: Consolidation Gaps epic ### Reviewer Checklist As a reviewer, please check these items: - [ ] Shared code example boxes contain language-specific snippets or placeholders for every language - [ ] API reference details contain working API reference links or generic content - [ ] Realm naming/language has been updated - [ ] All relevant content from individual SDK pages is present on the consolidated page
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
@@ -0,0 +1,8 @@
+You can read the user metadata of a currently logged-in user through the
+:dotnet-sdk:`User <reference/Realms.Sync.User.html>` object.
+
+The ``Profile`` property on the ``User`` object returns a 
+:dotnet-sdk:`UserProfile <reference/Realms.Sync.UserProfile.html>` 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
@@ -0,0 +1,8 @@
+You can read the user metadata of a currently logged-in user through the
+:flutter-sdk:`User <realm/User-class.html>` object.
+
+The ``profile`` property on the ``User`` object returns a
+:flutter-sdk:`User.profile <realm/User/profile.html>` 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
@@ -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
@@ -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
@@ -0,0 +1,8 @@
+You can read the user metadata of a currently logged-in user through 
+that user's 
+:kotlin-sync-sdk:`User <io.realm.kotlin.mongodb/-user/index.html>` 
+object. You cannot edit user metadata through a ``User`` object. 
+
+To read the data, call the :kotlin-sync-sdk:`profileAsBsonDocument
+<io.realm.kotlin.mongodb.ext/profile-as-bson-document.html>`
+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
@@ -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()
+  <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 the Kotlin SDK's EJSON serialization.
+For more information, refer to :ref:`Serialization <sdks-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
@@ -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
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
@@ -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
diff --git 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
+   <configure-user-metadata-on-the-backend>`. 
+
+.. _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 <configure-user-metadata-on-the-backend>`.
+
+.. 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

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+The selected language does not provide serializable user metadata. This`
	`2`	`+functionality is only available in Kotlin.`