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()

Connect to a Different Server During Runtime

In some cases, you might want to change the baseUrl while the app is running.

To change the baseUrl during runtime, call the experimental app.updateBaseUrl method. You can pass null to reset the baseUrl to the default value.

// Specify a custom baseUrl to connect to.
// In this case, an Edge Server instance running on the device:
val config = AppConfiguration.Builder(EDGE_SERVER_APP_ID)
    .baseUrl("http://localhost:80")
    .build()
val app = App.create(config)
// ... log in a user and use the app ...
// Later, change the baseUrl.
// In this case, pass `null` to reset to default:
// https://services.cloud.mongodb.com
app.updateBaseUrl(null)

If you change the baseUrl after you have logged in a user and have opened a synced database, the app must perform a client reset. For more information, refer to Handle Client Reset Errors.

Perform the following in your code:

1. Pause the Sync session

2. Update the baseUrl using the app.updateBaseUrl method

3. Re-authenticate the user to log in using the new baseUrl

4. 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.