Connect to App Services - Flutter SDK

Before You Begin

1. Create an App Services App

2. Find the App ID in the App Services UI

Access the App Client

Create an App instance to access App Services features throughout your client application. We recommend that you create the App instance only once on the main isolate, ideally as soon as the app starts.

1. Get your App Services App's ID from the App Services UI. To learn how, refer to Find your App ID.

2. Create an AppConfiguration object with your App's App ID as the argument.

3. Create an App with the AppConfiguration you just created. In Flutter v1.7.0 and later, this must be done on the main isolate, otherwise the SDK throws an error.

After you create the App, you can access the constructed App instance on a background isolate using App.getById. Refer to the Get App by ID section on this page for more information.

final appConfig = AppConfiguration(appId);
final app = App(appConfig);

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.

Advanced Configuration

You can add optional arguments to the AppConfiguration for more granular control of your App client. You may want to add things like custom timeouts for connections or keys for local metadata encryption. To learn about the available configuration options, refer to the AppConfiguration reference documentation.

final appConfig = AppConfiguration(appId,
    defaultRequestTimeout: const Duration(seconds: 120)
    // ... see reference docs for all available configuration options
    );

Get App by ID

After you have created an App instance on the main isolate, you can access the constructed instance on a background isolate by passing the App ID to the App.getById() method. Then, you can use it to work with the App and users as needed.

// Create an App instance once on main isolate,
// ideally as soon as the app starts
final appConfig = AppConfiguration(appId);
final app = App(appConfig);
final receivePort = ReceivePort();
// Later, access the App instance on background isolate
await Isolate.spawn((List<Object> args) async {
  final sendPort = args[0] as SendPort;
  final appId = args[1] as String;
  try {
    final backgroundApp = App.getById(appId); 
    // ... Access App users
    final user = backgroundApp?.currentUser!;
    // Use the App and user as needed.
    sendPort.send('Background task completed');
  } catch (e) {
    sendPort.send('Error: $e');
  }
}, [receivePort.sendPort, appId]);

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. For more information, refer to the Local Deployment App Services documentation.

• You want to connect to an Edge Server instance. For more information, refer to the Connect to the Edge Server from Atlas Device SDK App Services documentation.

You can specify a baseUrl in the AppConfiguration:

// Specify a baseUrl to connect to a server other than the default
final appConfig =
    AppConfiguration(appId, baseUrl: Uri.parse('https://example.com'));
var app = App(appConfig);

// Specify a custom baseUrl to connect to.
// In this case, an Edge Server instance running on the device.
final appConfig = AppConfiguration(edgeServerAppId,
    baseUrl: Uri.parse('http://localhost:80'));
var app = App(appConfig);
// ... log in a user and use the app ...
// Later, change the baseUrl to the default:
// https://services.cloud.mongodb.com
await app.updateBaseUrl(null);