Connect to App Services - C++ SDK

Prerequisites

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.

Access the App Client

1. Find the App ID in the Realm UI.

2. Create a realm::App::configuration() with with your App's ID as the argument. You can optionally configure additional details through the App configuration.

3. Initialize an App using this realm::App::configuration(). You use this App instance to access App Services features throughout your client application.

auto appConfig = realm::App::configuration();
appConfig.app_id = APP_ID;
auto app = realm::App(appConfig);

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 Realm C++ SDK supports setting custom HTTP headers on the realm::App::configuration() and on the realm::db_config.

When you initialize the App configuration, pass in a map of string header keys and values.

std::map<std::string, std::string> customHttpHeaders;
customHttpHeaders.emplace("CUSTOM_HEADER_NAME", "CUSTOM_HEADER_VALUE");
auto appConfig = realm::App::configuration();
appConfig.app_id = APP_ID;
appConfig.custom_http_headers = customHttpHeaders;
auto app = realm::App(appConfig);

If you call a function, the App uses these custom headers.

If you want to use custom headers with Device Sync, you must additionally set the headers on the realm::db_config.

Use an HTTP Proxy with Realm

If you have configured an HTTP proxy, you can use HTTP tunneling to route your Realm traffic.

To configure Realm to use your HTTP proxy:

1. Initialize a proxy_config with the details for your proxy.

2. Set the proxy config on your realm::App::configuration.

3. Set the proxy config on your realm::db_config.

auto proxyConfig = realm::proxy_config();
proxyConfig.port = 8080;
proxyConfig.address = "127.0.0.1";
proxyConfig.username_password = {"username", "password"};
auto appConfig = realm::App::configuration();
appConfig.app_id = APP_ID;
appConfig.proxy_configuration = proxyConfig;
auto app = realm::App(appConfig);
auto user = app.get_current_user();
auto syncConfig = user->flexible_sync_configuration();
syncConfig.set_proxy_config(proxyConfig);
auto syncedRealm = realm::db(syncConfig);

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 C++.

You can encrypt the metadata that App Services stores on client devices, similar to encrypting the realm.

On Apple devices, the metadata is encrypted by default. To disable this, add REALM_DISABLE_METADATA_ENCRYPTION to your environment variables.

To enable metadata encryption on other platforms, you must set a metadata_encryption_key on your realm::App::configuration.

// Check if we already have a key stored in the platform's secure storage.
// If we don't, generate a new one.
// Use your preferred method to generate a key. This example key is
// NOT representative of a secure encryption key. It only exists to
// illustrate the form your key might take.
std::array<char, 64> exampleKey = {
    0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0,
    0, 0, 3, 3, 0, 0, 0, 0, 0, 0, 4, 4, 0, 0, 0, 0, 0, 0, 5, 5, 0, 0,
    0, 0, 0, 0, 6, 6, 0, 0, 0, 0, 0, 0, 7, 7, 0, 0, 0, 0, 0, 0};
// Create and populate an App configuration.
auto appConfig = realm::App::configuration();
appConfig.app_id = APP_ID;
// Specify the metadata key.
appConfig.metadata_encryption_key = exampleKey;
// Use the configuration when you open the app.
auto app = realm::App(appConfig);