Install the Flutter SDK
You can use the Atlas Device SDK for Flutter in a Flutter project or in a standalone Dart project. This guide provides instructions for installing the SDK in both types of projects.
Prerequisites
To get started with the Atlas Device SDK for Flutter, you need to install the following, depending on the type of app you are developing:
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 install Dart in your development environment without Flutter. To learn how, refer to the official Dart Installation Guide.
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.
Supported Platforms
The Flutter SDK supports the following platforms:
iOS
Android
macOS
Windows running on 64-bit architecture
Linux running on 64-bit architecture
Important
Unsupported Platforms
The Flutter SDK does not support the following platforms:
Web
Windows running on ARM64 or 32-bit architectures
Linux running on ARM64 or 32-bit architectures
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:
realm: The Flutter SDK package for use in Flutter applications.realm_dart: The standalone Dart SDK package for use in Dart applications, such as CLI apps or running Dart in a server environment.
The standalone Dart package has the same usage as the Flutter package except where otherwise noted.
Tip
Atlas Device SDK and Realm
The Flutter SDK uses Realm Core database for device data persistence. When you install the Flutter SDK, the package names reflect Realm naming.
Create a Project
To create a Flutter project, run the following commands:
flutter create <app_name> cd <app_name>
For more information, refer to Flutter's Get Started Guide.
To create a Dart project, run the following commands:
dart create <app_name> cd <app_name>
For more information, refer to Dart's Get Started Guide for standalone Dart command-line and server applications.
Add the SDK to the Project
To add the Flutter SDK to your project, run the following command:
flutter pub add realm
This downloads the realm package, and adds it to your project.
In your pubspec.yaml file, you should see:
dependencies: realm: <latest_version>
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 Use Realm with the macOS App Sandbox.
To add the SDK to your project, run the following command:
dart pub add realm_dart
This downloads the realm_dart package, and adds it to your project.
In your pubspec.yaml file, you should see:
dependencies: realm_dart: <latest_version>
After the package is added, run the following command to install it:
dart run realm_dart install
This downloads and copies the required native binaries to the app directory.
Update the Package Version
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:
Install the Updated Package
Run the following command to install the updated version:
dependencies: realm: <updated_version>
Run the following command to install the updated version:
dart pub upgrade realm_dart
Then, run the following command to install the updated SDK's native binaries:
dart run realm_dart install
Regenerate Object Models
dart run realm generate
dart run realm_dart generate
Important
Flutter SDK v2.0.0 Breaking Change to Generated Files
Flutter SDK version 2.0.0 introduces an update to the
builder, which impacts how files generate. In v2.0.0 and later, all
generated files use the .realm.dart naming convention instead of .g.dart.
This is a breaking change for existing apps. For information on how to upgrade an existing app from an earlier SDK version to v2.0.0 or later, refer to Upgrade to Flutter SDK v2.0.0.
Troubleshooting
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.
For more information, refer to Delete a Realm File - Flutter SDK.
Apple Privacy Manifest
New in version 2.2.0.
Apple requires any apps or third-party SDKs that use required reasons APIs to provide a privacy manifest. The manifest contains details about the app's or SDK's data collection and use practices, and it must be included when submitting new apps or app updates to the Apple App Store. For more details about these requirements, refer to 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 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.xcprivacymacOS: https://github.com/realm/realm-dart/blob/main/packages/realm/macos/Resources/PrivacyInfo.xcprivacy
The Flutter SDK does not:
Include analytics code in builds for the App Store.
Log into Atlas on its own behalf.
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 initializes an App client to:
For more information, refer to Apple's Privacy Manifest Files documentation.