Docs Menu

Docs HomeAtlas Device SDK

Connect to Atlas App Services - Kotlin SDK

On this page

  • Prerequisites
  • Access the App Client
  • Configure the App Client
  • Share Sync Connections
  • Configure Sync Timeouts
  • Encrypt App Metadata
  • Set Custom HTTP Headers
  • Close the App Client

This page describes how to initialize your App client and connect to the Atlas App Services backend using the Kotlin SDK.

The App client is the interface to the App Services backend. It provides access to App Services functionality, including:

Each App client is associated with a single App ID.

Before you can connect to Atlas App Services, you need an App Services App with an App ID. To get started, refer to Create an App in the App Services documentation.

To learn how to find your App ID in the App Services UI, refer to Find Your App ID in the App Services documentation.

The Kotlin SDK uses the App interface to access an App client.

You can initialize an App with default configuration values using App.create(). You only need to pass the App ID for your App.

// Creates an App with default configuration values
val app = App.create(YOUR_APP_ID) // Replace with your App ID

Once you have initialized the App, you can use the App instance to access App Services functionality.

You can add optional arguments to the AppConfiguration for more granular control of your app connection details, such as custom request headers and keys for local encryption.

To control the additional configuration options, use the AppConfiguration.Builder and call the .build() method to pass a configuration object:

// Creates an App with custom configuration values
AppConfiguration.Builder(YOUR_APP_ID)
// Specify your custom configuration values
.appName("my-app-name")
.appVersion("1.0.0")
.baseUrl("http://localhost:9090")
.build()

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

You Can't Change an App Config After Initializing the App

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.

Note

Applies to Atlas Device Sync

This configuration option only applies to apps using Atlas Device Sync. For more information on using Device Sync with the Kotlin SDK, refer to Add Device Sync to an App - Kotlin SDK.

New in version 1.13.0.

By default, the SDK opens a separate connection to the server for each synced realm. In Kotlin v1.13.0 and later, you can enable session multiplexing. When enabled, the SDK shares a connection to the server for all synced realms opened with a single App Services user. Sharing a connection across multiple sessions reduces resources and can improve performance.

Multiplexing is disabled by default. You can enable it on the AppConfiguration using the .enableSessionMultiplexing() method, which accepts a Boolean value.

val config = AppConfiguration.Builder(YOUR_APP_ID)
.enableSessionMultiplexing(true)
.build()

When enabled, the shared connection does not immediately close when all sessions are closed. Instead, it remains open for the connectionLingerTime, which defaults to 30 seconds. You can override this duration by passing a new value to SyncTimeoutOptions.connectionLingerTime() on the AppConfiguration.

val configCustomLingerTime = AppConfiguration.Builder(YOUR_APP_ID)
.enableSessionMultiplexing(true)
.syncTimeouts {
connectionLingerTime = 10.seconds // Overrides default 30 secs
}
.build()

For more information, refer to the Configure Sync Timeouts section on this page.

Note

Applies to Atlas Device Sync

This configuration option only applies to apps using Atlas Device Sync. For more information on using Device Sync with the Kotlin SDK, refer to Add Device Sync to an App - Kotlin SDK.

New in version 1.13.0.

In Kotlin v1.13.0 and later, you can override the default timeout settings used when syncing data between the Atlas backend and the client app.

You can set various sync timeout settings on the AppConfiguration using the .syncTimeouts() method. Pass specific timeout property values you want to override. The configured timeouts apply to all sync sessions in the app.

val config = AppConfiguration.Builder(YOUR_APP_ID)
.syncTimeouts {
connectTimeout = 1.minutes
connectionLingerTime = 15.seconds
pingKeepalivePeriod = 30.seconds
pongKeepalivePeriod = 1.minutes
fastReconnectLimit = 30.seconds
}
.build()

For a complete list of the available timeout properties and their definitions, refer to the SyncTimeoutOptionsBuilder API reference.

When you connect to App Services, Realm creates additional metadata files on a device. For more information about these metadata files, refer to Atlas Device SDK for Kotlin.

You can encrypt the metadata that App Services stores on client devices, similar to how you Encrypt a Synced Realm.

To encrypt App metadata, pass your encryption key to the encryptionKey property when you initialize the App:

AppConfiguration.Builder(YOUR_APP_ID)
// Specify the encryption key
.encryptionKey(myEncryptionKey)
.build()

New in version 1.11.0.

If you use App Services or Device Sync with a proxy setup, you may need to set custom HTTP headers. The Realm Kotlin SDK supports setting custom HTTP headers on the App. These headers are appended to every request to the App Services App, including function calls.

When you initialize the App, you can pass:

AppConfiguration.Builder(YOUR_APP_ID)
.authorizationHeaderName("MyApp-Authorization")
.customRequestHeaders { put("X-MyApp-Version", "1.0.0") }
.build()

You can manually close an App instance and release all underlying resources using the App.close() method:

app.close()

If not closed manually, resources are freed when the App instance is garbage collected.

←  Atlas App Services - Kotlin SDKCall an Atlas Function - Kotlin SDK →