(DOCSP-39531): Consolidate Link User Identities page (#3350)

## Pull Request Info - SDK Docs Consolidation

Jira ticket: https://jira.mongodb.org/browse/DOCSP-39531
Jira ticket: https://jira.mongodb.org/browse/DOCSP-37351

*Staged Page*

- [Link User
Identities](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-39531/sdk/users/link-user-identities/)

*Page Source*

Add links to every SDK's pages where you got the SDK-specific
information:

- [Flutter: Link User
Identities](https://www.mongodb.com/docs/atlas/device-sdks/sdk/flutter/users/link-user-identities/)
- [Java: Link User
Identities](https://www.mongodb.com/docs/atlas/device-sdks/sdk/java/users/link-user-identities/)
- [Kotlin: Link User
Identities](https://www.mongodb.com/docs/atlas/device-sdks/sdk/kotlin/users/link-credentials/)
- [.NET: Link User
Identities](https://www.mongodb.com/docs/atlas/device-sdks/sdk/dotnet/manage-users/link-user-identities/)
- [Node.js: Link User
Identities](https://www.mongodb.com/docs/atlas/device-sdks/sdk/node/users/link-identities/)
- [Swift: Link User
Identities](https://www.mongodb.com/docs/atlas/device-sdks/sdk/swift/users/link-user-identities/)

### 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:

- [x] Shared code example boxes contain language-specific snippets or
placeholders for every language
- [x] API reference details contain working API reference links or
generic content
- [x] Realm naming/language has been updated
- [x] All relevant content from individual SDK pages is present on the
consolidated page

---------

Co-authored-by: Kyle Rollins <[email protected]>

source/includes/api-details/csharp/users/link-user-identities-example-description.rst

@@ -0,0 +1,13 @@
+You can link identities using the 
+:dotnet-sdk:`LinkCredentialsAsync() <reference/Realms.Sync.User.html#Realms_Sync_User_LinkCredentialsAsync_Realms_Sync_Credentials_>`. 
+This links the identity belonging to the credentials to the logged-in 
+:dotnet-sdk:`User <reference/Realms.Sync.User.html>` object. 
+
+.. literalinclude:: /examples/generated/dotnet/UserLinkExamples.snippet.link.cs
+   :language: csharp
+
+In the example above, we must first register the new :ref:`email/password
+<email-password-authentication>` user before linking. If you are using any of
+the other :ref:`Auth Providers <authentication-providers>`, this step is
+unnecessary. The following example uses :ref:`Google authentication
+<google-authentication>` instead of EmailPassword.

source/includes/api-details/dart/users/link-user-identities-example-description.rst

@@ -0,0 +1,8 @@
+You can link identities by passing the :flutter-sdk:`Credentials <realm/Credentials-class.html>`
+that you want to link to :flutter-sdk:`User.linkCredentials() <realm/User/linkCredentials.html>`.
+
+.. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.link-user-credentials.dart
+   :language: dart
+
+In the example below, we register an anonymous user, then later register an
+email/password user and link the credentials.

source/includes/api-details/java/users/link-user-identities-example-description.rst

@@ -0,0 +1,6 @@
+You link identities using
+:java-sdk:`linkCredentials() <io/realm/mongodb/User.html#linkCredentials(io.realm.mongodb.Credentials)>`
+or :java-sdk:`linkCredentialsAsync()
+<io/realm/mongodb/User.html#linkCredentialsAsync(io.realm.mongodb.Credentials,io.realm.mongodb.App.Callback)`.
+This links the new user identity to the logged-in :java-sdk:`User 
+<io/realm/mongodb/User.html>` object.

source/includes/api-details/javascript/users/link-user-identities-example-js-ts-description.rst

@@ -0,0 +1,4 @@
+
+You can link identities using :js-sdk:`linkCredentials()
+<classes/User.html#linkCredentials>`. This links the identity that belongs
+to the credential to a logged-in ``User`` object.

source/includes/api-details/kotlin/users/link-user-identities-example-description.rst

@@ -0,0 +1,4 @@
+You link identities using 
+:kotlin-sync-sdk:`linkCredentials <io.realm.kotlin.mongodb/-user/link-credentials.html>`.
+This links the identity belonging to the credential to the logged-in 
+:kotlin-sync-sdk:`User <io.realm.kotlin.mongodb/-user/index.html>`.

source/includes/api-details/objectivec/users/link-user-identities-example-description.rst

@@ -0,0 +1,4 @@
+You can link identities using :objc-sdk:`-linkUserWithCredentials:completion:
+<Classes/RLMUser.html#/c:objc(cs)RLMUser(im)linkUserWithCredentials:completion:>`.
+This links the identity that belongs to the credential to a logged-in ``User``
+object.

source/includes/api-details/swift/users/link-user-identities-example-description.rst

@@ -0,0 +1,10 @@
+You can link identities using :swift-sdk:`linkUser(credentials:)
+<Extensions/User.html#/s:So7RLMUserC10RealmSwiftE8linkUser11credentials7Combine6FutureCyABs5Error_pGAC11CredentialsO_tF>`.
+This links the identity that belongs to the credential to a logged-in ``User``
+object.
+
+.. literalinclude:: /examples/generated/code/start/MultipleUsers.snippet.link-identity.swift
+   :language: swift
+
+The SDK also provides an :swift-sdk:`async/await version of 
+User.linkUser <Extensions/User.html#/s:So7RLMUserC10RealmSwiftE8linkUser11credentials7Combine6FutureCyABs5Error_pGAC11CredentialsO_tF>`.

source/includes/sdk-examples/users/link-user-identities-example.rst

@@ -0,0 +1,58 @@
+.. tabs-drivers::
+
+   tabs:
+     - id: csharp
+       content: |
+
+         .. literalinclude:: /examples/generated/dotnet/UserLinkExamples.snippet.link2.cs
+            :language: csharp
+
+     - id: dart
+       content: |
+
+         .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.link-user-credentials-example.dart
+            :language: dart
+
+     - id: java
+       content: |
+
+         .. literalinclude:: /examples/generated/java/sync/LinkUserIdentitiesTest.snippet.link-users.java
+            :language: java
+
+     - id: java-kotlin
+       content: |
+
+         .. literalinclude:: /examples/generated/java/sync/LinkUserIdentitiesTest.snippet.link-users.kt
+            :language: kotlin
+
+     - id: javascript
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/link-identities.snippet.link-identities.js
+            :language: javascript
+            :emphasize-lines: 6
+
+     - id: kotlin
+       content: |
+
+         .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.link-credentials.kt
+            :language: kotlin
+
+     - id: objectivec
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/MultipleUsers.snippet.link-identity-objc.m
+            :language: objectivec
+
+     - id: swift
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/MultipleUsers.snippet.async-link-identity.swift
+            :language: swift
+
+     - id: typescript
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/link-identities.snippet.link-identities.ts
+            :language: typescript
+            :emphasize-lines: 10

source/sdk/users/link-user-identities.txt

@@ -4,10 +4,91 @@
 Link User Identities
 ====================
 
-.. contents:: On this page
-   :local:
-   :backlinks: none
-   :depth: 2
-   :class: singlecol
+.. meta::
+   :description: You can link user identities to associate multiple sets of credentials with the same user object.
+   :keywords: Realm, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example
 
-Placeholder page for information about linking user identities.
+.. facet::
+  :name: genre
+  :values: reference
+
+.. facet::
+   :name: programming_language
+   :values: csharp, dart, java, javascript/typescript, kotlin, objective-c, swift
+
+.. tabs-selector:: drivers
+
+Atlas Device SDK provides :ref:`many authentication providers
+<authentication-providers>` to log users into your app. Each provider has its
+own credentials that create a unique user identity. The SDK lets you merge
+multiple identities into a single user account.
+
+User identities must be linked prior to logging a user in. Once the user is
+logged in, you cannot link the credential used to login to the user account. 
+Also, you cannot link multiple email/password identities together.
+
+Example
+-------
+
+Consider an application that offers :ref:`anonymous login
+<anonymous-authentication>`, which allows users to explore the app without 
+registering. If a user wants to continue using the application, they can
+create a permanent account with an authentication provider intended to
+persist user data over a longer period, such as email/password authentication.
+The SDK creates a new identity belonging to a new ``User`` object. The app can
+then link the new identity with the current user.
+
+.. note:: 
+
+   Depending on how you have configured email/password authentication, there may 
+   be additional steps (confirming the email address, for example) before the 
+   new account is created and can be linked.
+
+.. tabs-drivers::
+
+   .. tab::
+      :tabid: csharp
+
+      .. include:: /includes/api-details/csharp/users/link-user-identities-example-description.rst
+
+   .. tab::
+      :tabid: dart
+
+      .. include:: /includes/api-details/dart/users/link-user-identities-example-description.rst
+
+   .. tab::
+      :tabid: java
+
+      .. include:: /includes/api-details/java/users/link-user-identities-example-description.rst
+
+   .. tab::
+      :tabid: java-kotlin
+
+      .. include:: /includes/api-details/java/users/link-user-identities-example-description.rst
+
+   .. tab::
+      :tabid: javascript
+
+      .. include:: /includes/api-details/javascript/users/link-user-identities-example-js-ts-description.rst
+
+   .. tab::
+      :tabid: kotlin
+
+      .. include:: /includes/api-details/kotlin/users/link-user-identities-example-description.rst
+
+   .. tab::
+      :tabid: objectivec
+
+      .. include:: /includes/api-details/objectivec/users/link-user-identities-example-description.rst
+
+   .. tab::
+      :tabid: swift
+
+      .. include:: /includes/api-details/swift/users/link-user-identities-example-description.rst
+
+   .. tab::
+      :tabid: typescript
+
+      .. include:: /includes/api-details/javascript/users/link-user-identities-example-js-ts-description.rst
+
+.. include:: /includes/sdk-examples/users/link-user-identities-example.rst