Connect to an Atlas App Services Backend - Swift SDK
On this page
The App client is the interface to the App Services backend. It provides access to the authentication functionality, functions, querying a MongoDB Atlas data source, and Device Sync.
Note
Apple Privacy Manifest
The SDK's Apple privacy manifest does not cover connecting to Atlas, or any usage of data through the App client. If your app connects to App Services, and you intend to distribute it through the Apple App Store, you may need to provide your own disclosures in your app's Apple privacy manifest.
For more information, refer to Apple Privacy Manifest.
Access the App Client
Pass the App ID for your App, which you can find in the App Services UI.
let app = App(id: YOUR_APP_SERVICES_APP_ID) // replace YOUR_APP_SERVICES_APP_ID with your App ID
Configuration
You can pass a configuration object to App
:
let configuration = AppConfiguration( baseURL: "https://services.cloud.mongodb.com", // You can customize base URL transport: nil, // Custom RLMNetworkTransportProtocol defaultRequestTimeoutMS: 30000 ) let app = App(id: "my-app-services-app-id", configuration: configuration)
You can create multiple App client instances to connect to multiple Apps. All App client instances that share the same App ID use the same underlying connection.
Important
Changing an App Config After Initializing the App
Starting with Swift SDK version 10.46.0, you can change a baseURL
in the App config and the App client uses the new baseURL
. In Swift
SDK versions 10.45.3 and earlier, when you initialize the App client,
the configuration is cached internally. Attempting to close an App and
then re-open it with a changed configuration within the same process has
no effect. The client continues to use the cached configuration.
Sync Connection Sharing
New in version 10.41.0.
You can set the enableSessionMultiplexing
bool on the
AppConfiguration to specify
whether the Realm Swift SDK should open a connection to the server for each
synced realm, or share a connection to the server for all synced realms.
If you do not specify a value for this bool, Realm defaults to sharing a single connection per App Services user for all synced realms.
let configuration = AppConfiguration(enableSessionMultiplexing: false) let app = App(id: YOUR_APP_SERVICES_APP_ID, configuration: configuration)
Sync Timeout Options
New in version 10.41.0.
You can set various sync timeout options on the
AppConfiguration. The
syncTimeouts
property can accept a SyncTimeoutOptions
object to
override default values for these settings.
For a complete list of the available timeout settings and their definitions, refer to RLMSyncTimeoutOptions.
let syncTimeoutOptions = SyncTimeoutOptions( connectTimeout: 30000, connectionLingerTime: 5000, pingKeepalivePeriod: 10000, pongKeepaliveTimeout: 10000, fastReconnectLimit: 30000 ) let configuration = AppConfiguration(syncTimeouts: syncTimeoutOptions) let app = App(id: YOUR_APP_SERVICES_APP_ID, configuration: configuration)
Connect to a Specific Server
By default, Atlas Device SDK connects to Atlas using the global baseURL
of https://services.cloud.mongodb.com
. In some cases, you may want to
connect to a different server:
Your App Services App uses local deployment, and you want to connect directly to a local
baseURL
in your region.
You can specify a baseURL
in the
AppConfiguration:
// Specify a baseURL to connect to a server other than the default. // In this case, an Edge Server instance running on the device. let configuration = AppConfiguration(baseURL: "http://localhost:80") let edgeApp = App(id: EDGE_SERVER_APP_ID, configuration: configuration)
Connect to a Different Server During Runtime
New in version 10.50.0.
In some cases, you might want to change the baseURL
while the app is
running. To change
the baseURL
during runtime, call the app.updateBaseUrl(to: )
method:
// Specify a baseURL to connect to a server other than the default. // In this case, an Edge Server instance running on the device. let configuration = AppConfiguration(baseURL: "http://localhost:80") let edgeApp = App(id: EDGE_SERVER_APP_ID, configuration: configuration) // You can check the `baseURL` of an app to define app logic. if edgeApp.baseURL == "http://localhost:80" { print("Client app is currently connected to a local Edge Server instance") } // ... log in a user and use the app... // ... some time later... try await edgeApp.updateBaseUrl(to: "https://services.cloud.mongodb.com")
This API is experimental, so you must use the experimental import in the file where you want to use this API:
RealmSwiftExperimental) import RealmSwift (
If you want to change the baseURL
after you have logged in a user and
have opened a synced database, the app must perform a
client reset. Perform these steps in your code:
Update the
baseURL
by calling theapp.updateBaseUrl(to: )
method.Authenticate and log the user in again with the new
baseURL
.Open a synced database pulling data from the new server.
Both the server and the client must be online for the user to authenticate and connect to the new server. If the server is not online or the client does not have a network connection, the user cannot authenticate and open the database.
Supported Operating Systems
The Realm Swift SDK supports connecting to an Atlas App Services App for a range of Apple operating systems depending on the Xcode version and Realm Swift SDK version. Connecting to an App Services App enables:
Authentication and User Management
Calling an Atlas Function
Querying a MongoDB Atlas Data Source
Device Sync
For current information about supported operating systems, refer to OS Support.
At this time, the Realm Swift SDK does not support connecting to an App Services App from watchOS.