(DOCSP-39531): Consolidate Link User Identities page

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