Connect to Atlas App Services - Kotlin SDK

Default App Client

To initialize an App with default configuration values, pass the App ID for your App Services App to the App.create() method:

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

Configured App Client

The AppConfiguration interface lets you configure your App client with optional arguments for more granular control of your app connection details, such as custom request headers and keys for local encryption.

To control the 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()

Share Sync Connections

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.

Configure Sync Timeouts

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.

Encrypt App Metadata

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:

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

Set Custom HTTP Headers

If you use App Services or Device Sync with a proxy setup, you may need to set custom HTTP headers. The 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:

• the custom authorizationHeaderName String value

• any customRequestHeaders in a map of String header keys and values (SDK accepts empty values but not empty keys)

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

Enable Platform Networking

Atlas Device SDK's platform networking lets you use your platform's networking stack instead of the default WebSocket client for Device Sync traffic.

When enabled, you can configure applications running on Android and Java Virtual Machine (JVM) platforms to use managed WebSockets over OkHttp. Managed WebSockets provide advanced configuration support for proxies and firewalls that require authentication.

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

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