diff --git a/source/includes/api-details/csharp/users/link-user-identities-example-description.rst b/source/includes/api-details/csharp/users/link-user-identities-example-description.rst new file mode 100644 index 0000000000..02c230095c --- /dev/null +++ b/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() `. +This links the identity belonging to the credentials to the logged-in +:dotnet-sdk:`User ` object. + +.. literalinclude:: /examples/generated/dotnet/UserLinkExamples.snippet.link.cs + :language: csharp + +In the example above, we must first register the new :ref:`email/password +` user before linking. If you are using any of +the other :ref:`Auth Providers `, this step is +unnecessary. The following example uses :ref:`Google authentication +` instead of EmailPassword. diff --git a/source/includes/api-details/dart/users/link-user-identities-example-description.rst b/source/includes/api-details/dart/users/link-user-identities-example-description.rst new file mode 100644 index 0000000000..f499d9eb83 --- /dev/null +++ b/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 ` +that you want to link to :flutter-sdk:`User.linkCredentials() `. + +.. 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. diff --git a/source/includes/api-details/java/users/link-user-identities-example-description.rst b/source/includes/api-details/java/users/link-user-identities-example-description.rst new file mode 100644 index 0000000000..79961a546c --- /dev/null +++ b/source/includes/api-details/java/users/link-user-identities-example-description.rst @@ -0,0 +1,6 @@ +You link identities using +:java-sdk:`linkCredentials() ` +or :java-sdk:`linkCredentialsAsync() +` object. diff --git a/source/includes/api-details/javascript/users/link-user-identities-example-js-ts-description.rst b/source/includes/api-details/javascript/users/link-user-identities-example-js-ts-description.rst new file mode 100644 index 0000000000..261bbc0b8b --- /dev/null +++ b/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() +`. This links the identity that belongs +to the credential to a logged-in ``User`` object. diff --git a/source/includes/api-details/kotlin/users/link-user-identities-example-description.rst b/source/includes/api-details/kotlin/users/link-user-identities-example-description.rst new file mode 100644 index 0000000000..660256c9e0 --- /dev/null +++ b/source/includes/api-details/kotlin/users/link-user-identities-example-description.rst @@ -0,0 +1,4 @@ +You link identities using +:kotlin-sync-sdk:`linkCredentials `. +This links the identity belonging to the credential to the logged-in +:kotlin-sync-sdk:`User `. diff --git a/source/includes/api-details/objectivec/users/link-user-identities-example-description.rst b/source/includes/api-details/objectivec/users/link-user-identities-example-description.rst new file mode 100644 index 0000000000..364badc565 --- /dev/null +++ b/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: +`. +This links the identity that belongs to the credential to a logged-in ``User`` +object. diff --git a/source/includes/api-details/swift/users/link-user-identities-example-description.rst b/source/includes/api-details/swift/users/link-user-identities-example-description.rst new file mode 100644 index 0000000000..899ac48577 --- /dev/null +++ b/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:) +`. +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 `. diff --git a/source/includes/link-user-identities.rst b/source/includes/link-user-identities.rst deleted file mode 100644 index d673ce95a5..0000000000 --- a/source/includes/link-user-identities.rst +++ /dev/null @@ -1,24 +0,0 @@ -Realm provides :ref:`many authentication providers ` -to log users into your app. Each provider creates a unique user identity. -Realm lets you merge multiple credentials into one user identity. - -Credentials must be linked prior to logging a user in. Once credentials are used -to login a user, you cannot link that credential anymore. -Also, you cannot link multiple email/password credentials together. - -Example -------- - -Consider an application that offers :ref:`anonymous login -`, which allows users to explore the app without -registering. If a user wants to continue using the application, they can create -a permanent account by using another authentication provider. Realm -creates 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. - \ No newline at end of file diff --git a/source/includes/sdk-examples/users/link-user-identities-example.rst b/source/includes/sdk-examples/users/link-user-identities-example.rst new file mode 100644 index 0000000000..5a2204de5b --- /dev/null +++ b/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 diff --git a/source/sdk/users/link-user-identities.txt b/source/sdk/users/link-user-identities.txt index fcc8a8d129..4131432c39 100644 --- a/source/sdk/users/link-user-identities.txt +++ b/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 +` 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 +`, 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