Draft Add Sync to App page

source/includes/api-details/csharp/sync/add-sync-to-app-define-sync-configuration-description.rst

@@ -0,0 +1,24 @@
+Device Sync requires a :dotnet-sdk:`FlexibleSyncConfiguration 
+<reference/Realms.Sync.FlexibleSyncConfiguration.html>`
+object to open a synced database. Note that 
+this is different than the :dotnet-sdk:`RealmConfiguration
+<reference/Realms.RealmConfiguration.html>` object that specifies some of the
+base database options.
+
+The ``FlexibleSyncConfiguration`` object requires an authenticated **User**.
+
+You can optionally provide an **Initial Subscription**. This is the
+subscription query that specifies the data to sync when the synced database is 
+opened. You can update your subscriptions after you open the database.
+
+If you do not provide an initial subscription as part of the Sync
+configuration, you must manually add subscriptions before you can read from or
+write to the database.
+
+Refer to :ref:`sdks-manage-sync-subscriptions` for more information.
+
+For additional database configuration parameters, refer to 
+:ref:`sdks-configure-and-open-synced-database`.
+
+For our example app, we define a configuration with an initial subscription
+that queries all ``MyTask`` objects.

source/includes/api-details/csharp/sync/add-sync-to-app-example-data-model-description.rst

@@ -0,0 +1,7 @@
+The examples on this page refer to an example Todo app with an already-defined
+``Item`` model that has:
+
+- An ObjectId ``_id`` property
+- A string ``Name`` property
+- An ``ItemStatus`` enum property
+- A string ``Assignee`` property

source/includes/api-details/csharp/sync/add-sync-to-app-use-synced-database-description.rst

@@ -0,0 +1,2 @@
+The following code demonstrates two ways to create a new ``Task`` object and 
+add it to the database.

source/includes/api-details/dart/sync/add-sync-to-app-define-sync-configuration-description.rst

@@ -0,0 +1,14 @@
+Device Sync requires a :flutter-sdk:`FlexibleSyncConfiguration 
+<realm/FlexibleSyncConfiguration-class.html>`
+object to open a synced database. Note that 
+this is different than the :flutter-sdk:`Configuration
+<realm/Configuration-class.html>` object that specifies some of the
+base database options.
+
+The ``FlexibleSyncConfiguration`` object requires an authenticated **User**.
+
+For additional database configuration parameters, refer to 
+:ref:`sdks-configure-and-open-synced-database`.
+
+For our example app, we define a configuration to manage objects conforming to
+``Car.schema``.

source/includes/api-details/dart/sync/add-sync-to-app-example-data-model-description.rst

@@ -0,0 +1,3 @@
+The examples on this page refer to an example app with an already-defined
+data model that includes a ``Car`` object containing an ``ObjectId`` and a
+string car ``model``.

source/includes/api-details/dart/sync/add-sync-to-app-open-synced-database-description.rst

@@ -0,0 +1,4 @@
+After you open the database, you must add subscriptions before you can read from or
+write to the database.
+
+Refer to :ref:`sdks-manage-sync-subscriptions` for more information.

source/includes/api-details/dart/sync/add-sync-to-app-use-synced-database-description.rst

@@ -0,0 +1 @@
+The following code creates a new ``Car`` object and writes it to the database:

source/includes/api-details/kotlin/sync/add-sync-to-app-define-sync-configuration-description.rst

@@ -0,0 +1,24 @@
+Device Sync requires a :kotlin-sync-sdk:`SyncConfiguration 
+<io.realm.kotlin.mongodb.sync/-sync-configuration/index.html>`
+object to open a synced database. Note that 
+this is different than the ``RealmConfiguration`` object that specifies some
+of the base database options.
+
+The ``SyncConfiguration`` object requires the following:
+
+- **User**: the authenticated user object.
+- **Schema**: all object types that you want to include in this database. 
+- **Initial Subscription**: the subscription query 
+ that specifies the data to sync when the synced database is 
+ initially opened. You can update your subscriptions 
+ after the database is opened. Refer to 
+ :ref:`sdks-manage-sync-subscriptions` for more information.
+
+For additional configuration parameters, refer to 
+:ref:`sdks-configure-and-open-synced-database`.
+
+For our example app, we define a configuration with: 
+
+- a schema that includes our ``List`` and ``Item`` objects
+- an initial subscription that queries all ``List`` objects 
+ that the user owns and all incomplete ``Item`` objects

source/includes/api-details/kotlin/sync/add-sync-to-app-example-data-model-description.rst

@@ -0,0 +1,3 @@
+The examples on this page refer to an example Todo app with an already-defined
+data model that includes a ``List`` object containing a list of ``Item``
+objects.

source/includes/api-details/kotlin/sync/add-sync-to-app-open-synced-database-description.rst

@@ -0,0 +1,11 @@
+For our example app, we pass our ``config`` object to 
+``realm.open()`` to open a synced database, then wait for 
+our subscriptions to sync with the backend.
+
+Because we have Development Mode enabled, Device Sync
+automatically adds the following as queryable fields based on 
+our initial subscription:
+
+- ``_id`` (always included)
+- ``ownerId``
+- ``complete``

source/includes/api-details/kotlin/sync/add-sync-to-app-prerequisites-description.rst

@@ -0,0 +1,4 @@
+Atlas Device SDK for Kotlin has a separate distribution to add App Services
+and Device Sync functionality to an app. If you haven't already added it,
+update your dependencies to include the Sync distribution of the Kotlin library.
+For more details, refer to :ref:`sdks-install`.

source/includes/api-details/kotlin/sync/add-sync-to-app-use-synced-database-description.rst

@@ -0,0 +1,9 @@
+For our example app, we write a new ``List`` and ``Item`` object, 
+then copy them to the synced database.
+
+The objects successfully write to the device, then sync to Atlas because: 
+
+- Both objects are within the parameters of the subscription query 
+ (the ``List`` is owned by the user and the ``Item`` is incomplete). 
+- The current user has permission to write data to the backend (the role allows 
+ authorized users to read and write all data).

source/includes/api-details/swift/sync/add-sync-to-app-define-sync-configuration-description.rst

@@ -0,0 +1,25 @@
+Device Sync requires a :swift-sdk:`FlexibleSyncConfiguration 
+<Extensions/User.html#/s:So7RLMUserC10RealmSwiftE25flexibleSyncConfiguration15clientResetMode31cancelAsyncOpenOnNonFatalErrors20initialSubscriptions05rerunmL0AC0B0V0F0VAC06ClienthI0O_SbyAC0E15SubscriptionSetVcSbtF>`
+object to open a synced database. Note that 
+this is different than the :swift-sdk:`Configuration
+<Structs/Realm/Configuration.html>` object that specifies some of the base
+database options.
+
+The ``FlexibleSyncConfiguration`` can take an ``initialSubscriptions`` block
+paired with a ``rerunOnOpen`` bool. The initial subscriptions are the
+subscription queries that specify what data to sync when the synced database
+is first opened. If your app needs it, you can pair this with ``reRunOnOpen``
+to recalculate dynamic queries every time the app opens, such as syncing
+documents within a date range.
+
+You can update your subscriptions after the database is opened. Refer to
+:ref:`sdks-manage-sync-subscriptions` for more information.
+
+For additional configuration parameters, refer to 
+:ref:`sdks-configure-and-open-synced-database`.
+
+For our example app, we define a configuration with: 
+
+- an initial subscription that queries ``Todo`` objects 
+ for documents where the ``ownerId`` matches the ``user.id`` of the logged-in user
+- a schema that includes our ``Todo`` object type

source/includes/api-details/swift/sync/add-sync-to-app-example-data-model-description.rst

@@ -0,0 +1,2 @@
+In this example, our model includes an ``ownerId`` field that maps to the
+``user.id`` of the logged-in user.

source/includes/api-details/swift/sync/add-sync-to-app-use-synced-database-description.rst

@@ -0,0 +1 @@
+The following code creates a new ``Task`` object and writes it to the database.

source/includes/sdk-examples/sync/add-sync-to-app-authenticate-user.rst

@@ -0,0 +1,26 @@
+.. tabs-drivers::
+
+ tabs:
+ - id: csharp
+ content: |
+
+ .. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.logon_anon.cs
+ :language: csharp
+
+ - id: dart
+ content: |
+
+ .. literalinclude:: /examples/generated/flutter/add_sync_to_app.snippet.log-in.dart
+ :language: dart
+
+ - id: kotlin
+ content: |
+
+ .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.authenticate-user.kt
+ :language: kotlin
+
+ - id: swift
+ content: |
+
+ .. literalinclude:: /examples/generated/code/start/AddSyncToApp.snippet.authenticate-user.swift
+ :language: swift

source/includes/sdk-examples/sync/add-sync-to-app-connect-to-atlas.rst

@@ -0,0 +1,26 @@
+.. tabs-drivers::
+
+ tabs:
+ - id: csharp
+ content: |
+
+ .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.initialize-realm.cs
+ :language: csharp
+
+ - id: dart
+ content: |
+
+ .. literalinclude:: /examples/generated/flutter/add_sync_to_app.snippet.connect-to-app.dart
+ :language: dart
+
+ - id: kotlin
+ content: |
+
+ .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.connect-to-backend.kt
+ :language: kotlin
+
+ - id: swift
+ content: |
+
+ .. literalinclude:: /examples/generated/code/start/AddSyncToApp.snippet.connect-to-backend.swift
+ :language: swift

source/includes/sdk-examples/sync/add-sync-to-app-define-sync-configuration.rst

@@ -0,0 +1,26 @@
+.. tabs-drivers::
+
+ tabs:
+ - id: csharp
+ content: |
+
+ .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.bootstrap-a-subscription.cs
+ :language: csharp
+
+ - id: dart
+ content: |
+
+ .. literalinclude:: /examples/generated/flutter/add_sync_to_app.snippet.opened-synced-realm.dart
+ :language: dart
+
+ - id: kotlin
+ content: |
+
+ .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.define-synced-realm.kt
+ :language: kotlin
+
+ - id: swift
+ content: |
+
+ .. literalinclude:: /examples/generated/code/start/AddSyncToApp.snippet.open-synced-realm.swift
+ :language: swift

source/includes/sdk-examples/sync/add-sync-to-app-example-data-model.rst

@@ -0,0 +1,28 @@
+.. tabs-drivers::
+
+ tabs:
+ - id: csharp
+ content: |
+
+ .. literalinclude:: /examples/MissingPlaceholders/example.cs
+ :language: csharp
+ :copyable: false
+
+ - id: dart
+ content: |
+
+ .. literalinclude:: /examples/MissingPlaceholders/example.dart
+ :language: dart
+ :copyable: false
+
+ - id: kotlin
+ content: |
+
+ .. literalinclude:: /examples/generated/kotlin/SchemaSync.snippet.sync-to-do-model.kt
+ :language: kotlin
+
+ - id: swift
+ content: |
+
+ .. literalinclude:: /examples/generated/code/start/AddSyncToApp.snippet.model.swift
+ :language: swift

source/includes/sdk-examples/sync/add-sync-to-app-open-synced-database.rst

@@ -0,0 +1,29 @@
+.. tabs-drivers::
+
+ tabs:
+ - id: csharp
+ content: |
+
+ .. literalinclude:: /examples/MissingPlaceholders/example.cs
+ :language: csharp
+ :copyable: false
+
+ - id: dart
+ content: |
+
+ .. literalinclude:: /examples/MissingPlaceholders/example.dart
+ :language: dart
+ :copyable: false
+
+ - id: kotlin
+ content: |
+
+ .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.open-synced-realm.kt
+ :language: kotlin
+
+ - id: swift
+ content: |
+
+ .. literalinclude:: /examples/MissingPlaceholders/example.swift
+ :language: swift
+ :copyable: false

source/includes/sdk-examples/sync/add-sync-to-app-use-synced-database.rst

@@ -0,0 +1,26 @@
+.. tabs-drivers::
+
+ tabs:
+ - id: csharp
+ content: |
+
+ .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.create.cs
+ :language: csharp
+
+ - id: dart
+ content: |
+
+ .. literalinclude:: /examples/generated/flutter/add_sync_to_app.snippet.write.dart
+ :language: dart
+
+ - id: kotlin
+ content: |
+
+ .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.write-to-synced-realm.kt
+ :language: kotlin
+
+ - id: swift
+ content: |
+
+ .. literalinclude:: /examples/generated/code/start/AddSyncToApp.snippet.create-todo.swift
+ :language: swift

source/sdk/crud/threading.txt

@@ -38,3 +38,4 @@ Frozen Objects
 Update a Frozen Object
 ~~~~~~~~~~~~~~~~~~~~~~
 
+.. _sdks-threading-three-rules: