initial draft

snooty.toml

@@ -49,7 +49,6 @@ toc_landing_pages = [
   "/sdk/react-native/sync-data",
   "/sdk/kotlin",
   "/sdk/kotlin/app-services",
-  "/sdk/kotlin/users",
   "/sdk/kotlin/realm-database",
   "/sdk/kotlin/realm-database/schemas",
   "/sdk/kotlin/realm-database/write-transactions",

source/examples/generated/kotlin/AuthenticationTest.snippet.access-token-refresh.kt

@@ -1,4 +1,3 @@
-// Gets the current refresh token for the user
 fun getRefreshToken(): String {
     return user.refreshToken
 }

source/examples/generated/kotlin/AuthenticationTest.snippet.anonymous-authentication-reuse-existing.kt

@@ -1,8 +1,6 @@
-runBlocking {
-    // Logs in with anonymous user
-    val anonUser = app.login(Credentials.anonymous())
+// Logs in with an anonymous user
+val anonUser = app.login(Credentials.anonymous())
 
-    // Creates a new anonymous user
-    val otherAnonUser =
-        app.login(Credentials.anonymous(reuseExisting = false))
-}
+// Logs in with a new, different anonymous user
+val otherAnonUser =
+    app.login(Credentials.anonymous(reuseExisting = false))

source/examples/generated/kotlin/AuthenticationTest.snippet.anonymous-authentication.kt

@@ -1,4 +1,5 @@
 val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
-runBlocking { // use runBlocking sparingly -- it can delay UI interactions
-    val user = app.login(Credentials.anonymous())
+runBlocking {
+    val anonymousCredentials = Credentials.anonymous()
+    val user = app.login(anonymousCredentials)
 }

source/examples/generated/kotlin/AuthenticationTest.snippet.api-key-authentication.kt

@@ -1,4 +1,4 @@
 val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
-runBlocking { // use runBlocking sparingly -- it can delay UI interactions
+runBlocking {
     val user = app.login(Credentials.apiKey(key))
 }

source/examples/generated/kotlin/AuthenticationTest.snippet.apple-authentication.kt

@@ -1,4 +1,6 @@
 val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
-runBlocking { // use runBlocking sparingly -- it can delay UI interactions
-    val user = app.login(Credentials.apple(idToken))
+runBlocking {
+    // Registration is handled by Apple
+    val appleCredentials = Credentials.apple(idToken)
+    val user = app.login(appleCredentials)
 }

source/examples/generated/kotlin/AuthenticationTest.snippet.auth-change-listener.kt

@@ -1,8 +1,9 @@
 // Create a Flow of AuthenticationChange objects
-app.authenticationChangeAsFlow().collect() { change: AuthenticationChange ->
-    when (change) {
-        is LoggedIn -> proceedToAppActivity(change.user)
-        is LoggedOut -> proceedToLoginActivity(change.user)
-        is Removed -> proceedToRemovedUserActivity(change.user)
-    }
+app.authenticationChangeAsFlow().collect {
+    change: AuthenticationChange ->
+        when (change) {
+            is LoggedIn -> proceedToAppActivity(change.user)
+            is LoggedOut -> proceedToLoginActivity(change.user)
+            is Removed -> proceedToRemovedUserActivity(change.user)
+        }
 }

source/examples/generated/kotlin/AuthenticationTest.snippet.create-new-user.kt

@@ -0,0 +1,10 @@
+// Instantiate your App Services App
+val app = App.create(YOUR_APP_ID) // Replace this with your App ID
+runBlocking {
+    // Log in the user with the credentials associated
+    // with the authentication provider
+    // If successful, returns an authenticated `User` object
+    val user = app.login(credentials)
+
+    // ... work with the user ...
+}

source/examples/generated/kotlin/AuthenticationTest.snippet.custom-function-authentication.kt

@@ -1,6 +1,5 @@
+// Create custom arguments for your Atlas Function
 val customCredentials = Credentials.customFunction(
     payload = mapOf("username" to "bob")
 )
-
-// Pass the generated credential to app.login()
-val currentUser = app.login(customCredentials)
+val user = app.login(customCredentials)

source/examples/generated/kotlin/AuthenticationTest.snippet.email-password-authentication.kt

@@ -1,4 +1,5 @@
 val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
-runBlocking { // use runBlocking sparingly -- it can delay UI interactions
-    val user = app.login(Credentials.emailPassword(email, password))
+runBlocking {
+    val emailPasswordCredentials = Credentials.emailPassword(email, password)
+    val user = app.login(emailPasswordCredentials)
 }

source/examples/generated/kotlin/AuthenticationTest.snippet.jwt-authentication.kt

@@ -1,4 +1,6 @@
 val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
-runBlocking { // use runBlocking sparingly -- it can delay UI interactions
-    val user = app.login(Credentials.jwt(jwtToken))
+runBlocking {
+    // Registration is handled by the JWT provider
+    val jwtCredentials = Credentials.jwt(jwtToken)
+    val user = app.login(jwtCredentials)
 }

source/examples/generated/kotlin/AuthenticationTest.snippet.link-credentials.kt

@@ -1,8 +1,8 @@
 val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
-runBlocking { // use runBlocking sparingly -- it can delay UI interactions
+runBlocking {
     val user = app.login(Credentials.anonymous()) // logs in with an anonymous user
     // registers an email/password user
     app.emailPasswordAuth.registerUser(email, password)
     // links anonymous user with email/password credentials
-    user.linkCredentials(Credentials.emailPassword(email, password));
+    user.linkCredentials(Credentials.emailPassword(email, password))
 }

source/examples/generated/kotlin/AuthenticationTest.snippet.log-out.kt

@@ -1,10 +1,10 @@
 val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
 runBlocking {
-    // Log user in
     val user = app.login(credentials)
 
-    // Work with logged-in user ...
+    // ... work with logged-in user ...
 
-    // Log user out
+    // Ensure all local updates are uploaded
+    // before logging out
     user.logOut()
 }

source/includes/tip-acct-deletion-reqs.rst

@@ -1,4 +1,4 @@
-.. tip:: Google and Apple Account Deletion Requirements
+.. important:: Google and Apple Account Deletion Requirements
 
    `Google <https://support.google.com/googleplay/android-developer/answer/13316080?sjid=9059006274298096173-NA#account_deletion>`__ 
    and :apple:`Apple <app-store/review/guidelines/#5.1.1>` require that 

source/sdk/kotlin/users.txt

@@ -5,112 +5,19 @@ Manage Users - Kotlin SDK
 .. toctree::
    :titlesonly:
 
-   Create & Delete Users </sdk/kotlin/users/delete-users>
-   Authenticate Users </sdk/kotlin/users/authenticate-users>
+   Create & Authenticate Users </sdk/kotlin/users/authenticate-users>
    Manage Email/Password Users </sdk/kotlin/users/manage-email-password-users>
    Link User Identities </sdk/kotlin/users/link-credentials>
    Create & Manage User API Keys </sdk/kotlin/users/manage-user-api-keys>
-   Custom User Data </sdk/kotlin/users/custom-user-data>
-   User Metadata </sdk/kotlin/users/user-metadata>
-
-.. contents:: On this page
-   :local:
-   :backlinks: none
-   :depth: 2
-   :class: singlecol
-
-To access Atlas App Services and use Atlas Device Sync with the Realm Kotlin SDK,
-you must first authenticate a user with an App Services authentication provider.
-
-For more information on configuring App Services Authentication,
-refer to :ref:`App Services Authentication <users-and-authentication>` in the
-Atlas App Services documentation.
-
-.. _kotlin-creating-and-deleting-users:
-
-Create and Delete Users
------------------------
-
-For most :ref:`authentication methods <authentication-providers>`, Atlas App Services 
-automatically creates a :ref:`user object <user-objects>` the first time 
-a user authenticates. The only exception is email/password authentication. 
-When you use email/password authentication, you must :ref:`register 
-<kotlin-manage-email-password-users>` and :ref:`confirm 
-<kotlin-confirm-a-new-users-email-address>` a user before the user can 
-authenticate to an App Services App.
-
-If a user authenticates via more than one method,
-you can :ref:`link the user identities <kotlin-link-user-identities>`
-for each method to a single user account.
-
-You can also :ref:`delete users <kotlin-delete-users>`. Deleting a user
-removes metadata attached to the user from App Services, but does not delete user-entered
-data from the backend.
-
-.. include:: /includes/apple-account-deletion-requirements.rst
-
-.. _kotlin-access-the-app-client:
-
-Log Users In and Out
---------------------
-
-Use one or more :ref:`authentication providers <auth-providers>` to :ref:`log
-users in and out <kotlin-authenticate>` of your client app. You can:
-
-- Log users in with an existing social account, such as Apple, Facebook,
-  or Google.
-- Create new user accounts with App Services email/password management
-  or your own custom function or custom JWT user management.
-- Enable anonymous users to let users access your App Services App without persisting
-  user data.
-
-When you have a logged-in user, you can:
-
-- :ref:`Open a synced realm <kotlin-open-a-synced-realm>` with the user's
-  configuration object
-- :ref:`Run a backend function <kotlin-call-function>` as the logged-in user
-- :ref:`Log the user out <kotlin-logout>`
-- :ref:`Delete the user's account <kotlin-delete-users>`
-
-On successful login, the Kotlin SDK caches credentials on the device. You
-can bypass the login flow and access the cached user. Use this to open a
-realm or call an Atlas Function upon subsequent app opens.
-
-User Sessions
-~~~~~~~~~~~~~
-
-.. include:: /includes/manage-user-sessions.rst
-
-.. _kotlin-get-user-data:
-
-Get User Data
--------------
-
-App Services manages :ref:`user sessions <user-sessions>` with access tokens and refresh tokens.
-Client SDKs supply the logic to manage tokens, and provide them with requests.
-
-To learn more about the user object that App Services provides the Kotlin SDK,
-refer to the following documentation:
-
-- :ref:`User Objects <user-objects>` in the App Services documentation.
-- `User <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb/-user/index.html>`__ 
-  in the Kotlin SDK API reference documentation.
-
-Read and Update Custom User Data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can :ref:`associate custom data <custom-user-data>` with a user, 
-such as a preferred language or local timezone, and read it from your client application.
-
-For more information on working with custom user data,
-refer to :ref:`Custom User Data <kotlin-custom-user-data>`.
-
-Read User Metadata from Login Providers
----------------------------------------
-
-Some authentication providers enable developers to access 
-:ref:`user metadata <auth-provider-metadata>` , such as full name or email 
-address. When you configure these metadata fields on the App Services 
-application, you can access this metadata from you client app. 
-For more information on working with user metadata, refer to
-:ref:`Read a User's Metadata <kotlin-read-user-metadata>`. 
+   Delete Users </sdk/kotlin/users/delete-users>
+   Manage Custom User Data </sdk/kotlin/users/custom-user-data>
+   Manage User Metadata </sdk/kotlin/users/user-metadata>
+
+
+- :ref:`<kotlin-authenticate>`
+- :ref:`<kotlin-manage-email-password-users>`
+- :ref:`<kotlin-link-user-identities>`
+- :ref:`<kotlin-manage-user-api-keys>`
+- :ref:`<kotlin-delete-users>`
+- :ref:`<kotlin-custom-user-data>`
+- :ref:`<kotlin-read-user-metadata>`