From 9e5a999b8a73a7832f767a5707ca65c82cebdefc Mon Sep 17 00:00:00 2001 From: cbullinger Date: Wed, 8 May 2024 13:09:14 -0400 Subject: [PATCH] Update wording and fix tab formatting --- source/sdk/flutter/install.txt | 206 ++++++++++-------- .../realm-database/realm-files/delete.txt | 8 + source/sdk/swift/install.txt | 75 +++---- 3 files changed, 163 insertions(+), 126 deletions(-) diff --git a/source/sdk/flutter/install.txt b/source/sdk/flutter/install.txt index 83444434e2..fea5a9bd50 100644 --- a/source/sdk/flutter/install.txt +++ b/source/sdk/flutter/install.txt @@ -26,18 +26,17 @@ Prerequisites ------------- To get started with the Atlas Device SDK for Flutter, you need to install -Flutter or Dart: +the following, depending on the type of app you are developing: -- For Flutter or Dart apps, install Flutter in your development environment. - Note that the Flutter installation includes the full Dart SDK. To learn - how, refer to the official `Flutter Installation Guide - `__. +- For Flutter or Dart apps, install Flutter with Dart in your development environment. + The Flutter installation includes Dart. To learn how, refer to the official + `Flutter Installation Guide `__. -- For standalone Dart apps, you can choose install Dart in your development - environment without Flutter. To learn how, refer to the official `Dart - Installation Guide `__. +- For standalone Dart apps, you can install Dart in your development + environment without Flutter. To learn how, refer to the official + `Dart Installation Guide `__. -The latest version of the Device SDK for Flutter requires the following: +The latest version of the Flutter SDK requires the following minimum versions: - Flutter version 3.19.0 or later. - Dart version 3.3.0 or later. @@ -64,8 +63,8 @@ The Flutter SDK supports the following platforms: .. _flutter-install-steps: .. _dart-install-steps: -Installation ------------- +Install the SDK +--------------- The Atlas Device SDK for Flutter has two packages available to install, depending on whether you are developing a Flutter or Dart standalone app: @@ -79,8 +78,7 @@ where otherwise noted. .. tip:: Atlas Device SDK and Realm - The SDK uses Realm Core database for device data persistence. When you - install the Kotlin SDK, the package names reflect Realm naming. + The Flutter SDK uses Realm Core database for device data persistence. When you install the Flutter SDK, the package names reflect Realm naming. .. procedure:: @@ -93,7 +91,7 @@ where otherwise noted. To create a Flutter project, run the following commands: - .. code-block:: + .. code-block:: bash flutter create cd @@ -106,7 +104,7 @@ where otherwise noted. To create a Dart project, run the following commands: - .. code-block:: + .. code-block:: bash dart create cd @@ -122,9 +120,9 @@ where otherwise noted. .. tab:: Flutter :tabid: flutter - To add the SDK to your project, run the following command: + To add the Flutter SDK to your project, run the following command: - .. code-block:: + .. code-block:: bash flutter pub add realm @@ -139,12 +137,23 @@ where otherwise noted. dependencies: realm: - .. tab:: Standalone Dart - :tabid: dart + .. note:: Using Networking in your macOS App + + If you are developing with the Flutter SDK in the macOS App + Sandbox and require network access, you must enable network + entitlements in your app. By default, network requests are + not allowed due to built-in macOS security settings. + + To use networking in your macOS app, you must change your app's + macOS network entitlements. To learn how, refer to + :ref:`flutter-macos-development`. + + .. tab:: Standalone Dart + :tabid: dart - To add the SDK to your project, run the following command: + To add the SDK to your project, run the following command: - .. code-block:: + .. code-block:: bash dart pub add realm_dart @@ -162,7 +171,7 @@ where otherwise noted. After the package is added, run the following command to install it: - .. code-block:: + .. code-block:: bash dart run realm_dart install @@ -171,13 +180,14 @@ where otherwise noted. .. step:: Import the Package into Files + To use the SDK in your app, import the package into any files where you + will use it: + .. tabs:: .. tab:: Flutter :tabid: flutter - To use the Flutter SDK within your app, import the package into files where you will use it: - .. code-block:: dart :caption: ExampleFile.dart @@ -186,96 +196,105 @@ where otherwise noted. .. tab:: Standalone Dart :tabid: dart - To use the SDK within your Dart app, import the package into files where you will use it: - .. code-block:: dart :caption: ExampleFile.dart import 'package:realm_dart/realm.dart'; -.. note:: Using Networking in your macOS App +.. _flutter-update-package: - If you are developing with the Flutter SDK in the macOS App Sandbox, - network requests do *not* work by default. This is due to the built-in macOS - security settings. +Update the Package Version +-------------------------- - To use networking in your macOS app, you must change your app's macOS network - entitlements. To learn how, refer to :ref:`flutter-macos-development`. +To change the version of the SDK in your project, perform the following steps, +depending on whether you are using the ``realm`` or ``realm_dart`` package: -.. _flutter-update-package: +.. procedure:: -Update Package Version ----------------------- + .. step:: Update the ``pubspec.yaml`` File -.. include:: /includes/flutter-v2-breaking-change.rst + Update the package version in your :file:`pubspec.yaml` file dependencies. -To change the version of the SDK in your project, perform the following steps, -depending on whether you have a Flutter or Dart standalone app: + .. tabs:: -.. tabs:: + .. tab:: Flutter + :tabid: flutter - .. tab:: Flutter - :tabid: flutter + .. code-block:: yaml + :caption: pubspec.yaml - #. Add the new SDK version to your :file:`pubspec.yaml` file. + dependencies: + realm: - .. code-block:: yaml - :caption: pubspec.yaml + .. tab:: Dart Standalone + :tabid: dart - dependencies: - realm: + .. code-block:: yaml + :caption: pubspec.yaml + + dependencies: + realm_dart: + + .. step:: Install the Updated Package + + .. tabs:: + + .. tab:: Flutter + :tabid: flutter + + Run the following command to install the updated version: - #. Install the updated version. + .. code-block:: yaml + :caption: pubspec.yaml - .. code-block:: + dependencies: + realm: - flutter pub upgrade realm + .. tab:: Dart Standalone + :tabid: dart - #. Regenerate your object models. + Run the following command to install the updated version: - .. code-block:: + .. code-block:: bash - dart run realm generate + dart pub upgrade realm_dart - These steps should make the updated SDK version work in your application. - If issues persist, you can delete the application from your linked client and - restart it. Note that this will also delete all data stored in the database - on that client. + Then, run the following command to install the updated SDK's native + binaries: - .. tab:: Dart Standalone - :tabid: dart + .. code-block:: bash - #. Add the new SDK version to your :file:`pubspec.yaml` file. + dart run realm_dart install - .. code-block:: yaml - :caption: pubspec.yaml + .. step:: Regenerate Object Models - dependencies: - realm_dart: + .. tabs:: - #. Install the updated version. + .. tab:: Flutter + :tabid: flutter - .. code-block:: + .. code-block:: bash - dart pub upgrade realm_dart + dart run realm generate - #. Install the updated SDK's native binaries. + .. tab:: Dart Standalone + :tabid: dart - .. code-block:: + .. code-block:: bash - dart run realm_dart install + dart run realm_dart generate - #. Regenerate your object models. + .. include:: /includes/flutter-v2-breaking-change.rst - .. code-block:: +Troubleshooting +~~~~~~~~~~~~~~~ - dart run realm_dart generate +If you have issues using the updated SDK version in your application, you can +delete the ``.realm`` database file created by the SDK, and restart the +application. Note that deleting the ``.realm`` file also deletes all data stored +in the database on that client. - These steps should make the updated SDK version work in your application. - If issues persist, delete the ``.realm`` database file created by the SDK, - and restart the application. - Note that deleting the ``.realm`` file also deletes all data stored in - the database on that client. +For more information, refer to :ref:`flutter-delete-realm`. .. _flutter-apple-privacy-manifest: @@ -284,18 +303,21 @@ Apple Privacy Manifest .. versionadded:: 2.2.0 -Apple requires apps that use required reason APIs to provide details about the -SDK's data collection and use practices when submitting new apps or app updates -to the App Store. For more details about Apple's requirements, refer to -:apple:`support/third-party-SDK-requirements/` on the Apple Developer website. +Apple requires any apps or third-party SDKs that use *required reasons APIs* +to provide a privacy manifest containing details about their data collection +and use practices. The bundled manifest file must be included when submitting +new apps or app updates to the Apple App Store. For more details about these +requirements, refer to +:apple:`Upcoming third-party SDK requirements ` +on the Apple Developer website. Starting in Flutter SDK version 2.2.0, the SDK ships with a privacy manifest for ``iOS`` and ``macOS`` environments, contained in the ``realm`` package. Both privacy manifests contain Apple's required API disclosures and the reasons for using those APIs. -You can view the privacy manifests in the package or the ``realm-dart`` -GitHub repository: +You can view these privacy manifests in the SDK package or directly in the +``realm-dart`` GitHub repository: - ``iOS``: `https://github.com/realm/realm-dart/blob/main/packages/realm/ios/Resources/PrivacyInfo.xcprivacy @@ -309,15 +331,21 @@ The Flutter SDK does *not*: - Include analytics code in builds for the App Store. - Log into Atlas on its own behalf. -If you write an app that uses any App Services functionality, you may need to -add additional disclosures to your app's privacy manifest detailing your data -collection and use practices when using these APIs. -For example, if your app :ref:`initializes an App client -` to: +.. important:: Additional Disclosures May Be Required for App Services + + The Flutter SDK privacy manifest does *not* include disclosures for App + Services APIs. + +If your app uses any Atlas App Services functionality, such as user +authentication or Device Sync, you may need to provide additional disclosures +that detail your data collection and use practices when using these APIs. +For example, if your app +:ref:`initializes an App client ` to: - :ref:`Call an Atlas Function ` - :ref:`Authenticate and manage users ` - :ref:`Open a synced database ` For more information, refer to Apple's -:apple:`documentation/bundleresources/privacy_manifest_files` documentation. +:apple:`Privacy Manifest Files ` +documentation. diff --git a/source/sdk/flutter/realm-database/realm-files/delete.txt b/source/sdk/flutter/realm-database/realm-files/delete.txt index 9abd4a3cfb..73e853d774 100644 --- a/source/sdk/flutter/realm-database/realm-files/delete.txt +++ b/source/sdk/flutter/realm-database/realm-files/delete.txt @@ -4,6 +4,14 @@ Delete a Realm File - Flutter SDK ================================= +.. meta:: + :description: Delete the local realm files from disk. + :keywords: code example + +.. facet:: + :name: genre + :values: tutorial + .. contents:: On this page :local: :backlinks: none diff --git a/source/sdk/swift/install.txt b/source/sdk/swift/install.txt index 227e3efb18..acae84e2e9 100644 --- a/source/sdk/swift/install.txt +++ b/source/sdk/swift/install.txt @@ -4,8 +4,8 @@ Install the SDK for iOS, macOS, tvOS, and watchOS ================================================= -.. meta:: - :description: Install Atlas Device SDK for Swift using popular package managers, or as a static framework. +.. meta:: + :description: Install Atlas Device SDK for Swift using popular package managers, or as a static framework. .. facet:: :name: genre @@ -21,7 +21,7 @@ Overview -------- Atlas Device SDK for Swift enables you to build iOS, macOS, tvOS, -and watchOS applications using either the Swift or Objective-C programming +and watchOS applications using either the Swift or Objective-C programming languages. This page details how to install the SDK in your project and get started. @@ -33,10 +33,10 @@ meets the following prerequisites: - Your project uses an Xcode version and minimum OS version listed in the :ref:`swift-os-support` section of this page. -- Reflection is enabled in your project. The Swift SDK uses reflection to - determine your model's properties. Your project must not set - ``SWIFT_REFLECTION_METADATA_LEVEL = none``, or the SDK cannot see properties - in your model. Reflection is enabled by default if your project does +- Reflection is enabled in your project. The Swift SDK uses reflection to + determine your model's properties. Your project must not set + ``SWIFT_REFLECTION_METADATA_LEVEL = none``, or the SDK cannot see properties + in your model. Reflection is enabled by default if your project does not specifically set a level for this setting. Installation @@ -90,14 +90,14 @@ Swift SDK to your project. To use the Privacy Manifest supplied by the SDK, build ``RealmSwift`` as a dynamic framework. If you build ``RealmSwift`` as a static - framework, you must supply your own Privacy Manifest. - + framework, you must supply your own Privacy Manifest. + To build ``RealmSwift`` as a dynamic framework: 1. In your project :guilabel:`Targets`, select your build target. 2. Go to the :guilabel:`General` tab. 3. Expand the :guilabel:`Frameworks and Libraries` element. - 4. For the ``RealmSwift`` framework, change the + 4. For the ``RealmSwift`` framework, change the :guilabel:`Embed` option from "Do Not Embed" to "Embed & Sign." Now, Xcode builds ``RealmSwift`` dynamically, and can provide the @@ -283,15 +283,15 @@ Swift SDK to your project. target and go to the :guilabel:`Build Phases` tab. Under :guilabel:`Link Binary with Libraries`, click :guilabel:`+` and add ``libc++.tbd``, ``libz.tbd``, and ``libcompression.tbd``. - + .. tip:: - - If using the Objective-C API within a Swift project, we - recommend you include both Realm Swift and Realm Objective-C in your - project. Within your Swift files, you can access the Swift API and - all required wrappers. Using the RealmSwift API in mixed - Swift/Objective-C projects is possible because the vast majority of - RealmSwift types are directly aliased from their Objective-C + + If using the Objective-C API within a Swift project, we + recommend you include both Realm Swift and Realm Objective-C in your + project. Within your Swift files, you can access the Swift API and + all required wrappers. Using the RealmSwift API in mixed + Swift/Objective-C projects is possible because the vast majority of + RealmSwift types are directly aliased from their Objective-C counterparts. Import the SDK @@ -323,17 +323,17 @@ Add the following line at the top of your source files to use the SDK: App Download File Size ---------------------- -The SDK should only add around 5 to 8 MB to your app's download -size. The releases we distribute are significantly larger because they -include support for the iOS, watchOS and tvOS simulators, some debug symbols, -and bitcode, all of which are stripped by the App Store automatically when +The SDK should only add around 5 to 8 MB to your app's download +size. The releases we distribute are significantly larger because they +include support for the iOS, watchOS and tvOS simulators, some debug symbols, +and bitcode, all of which are stripped by the App Store automatically when apps are downloaded. Troubleshooting --------------- -If you have build issues after using one of these methods to install -the SDK, see :ref:`our troubleshooting guidelines ` +If you have build issues after using one of these methods to install +the SDK, see :ref:`our troubleshooting guidelines ` for information about resolving those issues. .. _swift-os-support: @@ -375,7 +375,7 @@ Xcode 15 * - watchOS 4.0+ - X - - + - * - visionOS 1.0+ - X @@ -397,7 +397,7 @@ Swift Concurrency Support ------------------------- The Swift SDK supports Swift's concurrency-related language features. -For best practices on using the Swift SDK's concurrency features, refer +For best practices on using the Swift SDK's concurrency features, refer to the documentation below. Async/Await Support @@ -422,9 +422,10 @@ Apple Privacy Manifest .. versionchanged:: 10.49.3 Build RealmSwift as a dynamic framework to include the Privacy Manifest. -Apple requires apps that use ``RealmSwift`` to provide details about the SDK's -data collection and use practices when submitting new apps or app updates to -the App Store. For more details about Apple's requirements, refer to +Apple requires apps that use ``RealmSwift`` to provide a privacy manifest +containing details about the SDK's data collection and use practices. The +bundled manifest file must be included when submitting new apps or app updates +to the App Store. For more details about Apple's requirements, refer to :apple:`Upcoming third-party SDK requirements ` on the Apple Developer website. @@ -432,7 +433,7 @@ Starting in Swift SDK version 10.46.0, the SDK ships with privacy manifests for ``Realm`` and ``RealmSwift``. Each package contains its own privacy manifest with Apple's required API disclosures and the reasons for using those APIs. -You can view the privacy manifests in each package, or in the ``realm-swift`` +You can view the privacy manifests in each package, or in the ``realm-swift`` GitHub repository: - ``Realm``: `https://github.com/realm/realm-swift/blob/master/Realm/PrivacyInfo.xcprivacy `_ @@ -440,13 +441,13 @@ GitHub repository: To include these manifests in a build target that uses ``RealmSwift``, you must build ``RealmSwift`` as a dynamic framework. For details, refer to the Swift -Package Manager Installation instructions step +Package Manager Installation instructions step **(Optional) Build RealmSwift as a Dynamic Framework**. -The Swift SDK does not include analytics code in builds for the App Store. -The SDK does not log into Atlas on its own behalf. +The Swift SDK does not include analytics code in builds for the App Store. +The SDK does not log into Atlas on its own behalf. -If you write an app that uses any App Services functionality, such as +If you write an app that uses any App Services functionality, such as :ref:`initializing an App client ` to: - :ref:`Call an Atlas Function ` @@ -454,8 +455,8 @@ If you write an app that uses any App Services functionality, such as - :ref:`Query MongoDB Atlas ` - :ref:`Open a synced database ` -You may need to add additional disclosures to your app's privacy manifest -detailing your data collection and use practices when using these APIs. +You may need to add additional disclosures to your app's privacy manifest +detailing your data collection and use practices when using these APIs. -For more information, refer to Apple's +For more information, refer to Apple's :apple:`Privacy manifest files documentation `.