Docs Menu

Docs HomeAtlas Device SDK

Connect to App Services - C++ SDK

On this page

  • Prerequisites
  • Access the App Client
  • Set Custom HTTP Headers
  • Use an HTTP Proxy with Realm
  • Encrypt App Metadata

The App client is the Atlas App Services backend interface. It provides access to authentication and Atlas Functions.

Some of your App Services App's features are associated with user accounts. For example, you need to authenticate a user before you can access your App's functions.

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.

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

Tip

Building an Android App

When building an Android app that uses the Realm C++ SDK, you must pass the filesDir.path to the file_path parameter in the db_config constructor. For more information, refer to: Build an Android App.

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.

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

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);
←  Application Services - C++ SDKCall a Function - C++ SDK →