Docs Menu

Docs HomeAtlas Device SDK

Connect to an Atlas App Services Backend - Node.js SDK

On this page

  • Before You Begin
  • Access the App Client
  • Retrieve an Instance of the App Client
  • Configure a Timeout for the App Client
  • Encrypt App Metadata

The App client is the interface to the Atlas App Services backend. It provides access to the authentication functionality, functions, and sync management.

  1. Create an App Services App

  2. Install the Realm Node.js SDK

To connect to the App Services backend from your client, you need to create a configuration object. Then, pass that configuration object to a Realm.App() instance.

You must include the id field and the App ID for your App Services App, which you can find in the App Services UI.

// Initialize your App.
const app = new Realm.App({
id: "<yourAppId>",
});

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

Changed in version 12.6.0.

When you initialize the App client, the configuration is cached internally. Attempting to "close" and then re-open an App with a changed configuration within the same process has no effect. The client continues to use the cached configuration.

Starting with Node.js SDK version 12.6.0, the baseUrl in the AppConfiguration is not cached. This means that you can change the baseUrl - including at runtime - and the App client will use the updated configuration. In earlier SDK versions, changes to the baseUrl in a cached App configuration have no effect.

To retrieve an instance of the App Client from anywhere in your application, call Realm.App.getApp() and pass in your App ID.

const app = Realm.App.getApp("<yourAppId>");

You can configure an optional timeout for requests in your AppConfiguration. It accepts a number of milliseconds before the request should timeout.

You can use this timeout interval with the optional Sync configuration cancelWaitsOnNonFatalErrors boolean. When the timeout interval elapses, any outstanding work that is awaiting uploads and downloads cancels. When this setting is false, awaiting uploads and downloads does not cancel because Realm treats these timeouts as non-fatal errors.

For an example, refer to Cancel Asynchronous Operations after a Timeout.

const app = new Realm.App({
id: APP_ID,
// You can optionally specify a timeout in milliseconds
timeout: 10000,
});

You can encrypt the metadata that App Services stores on client devices. Use the values of the MetadataMode enum to determine encryption behavior.

To encrypt App metadata:

  1. Import MetadataMode from Realm and import other dependencies:

  2. Create an App configuration object that contains the metadata property.

  3. Set metadata.mode to MetadataMode.Encryption.

  4. Set metadata.encryptionKey to the key you want to use for encryption.

  5. Pass the App configuration object to new Realm.App().

←  Application Services - Node.js SDKCall a Function - Node.js SDK →