If you're upgrading from
v1.5.10 or earlier, please note that configuration data will no longer be embedded in our SDK package directory, and instead relocated to your project's Assets folder under
Assets/Embrace. Any previously defined configurations will be automatically converted at installation time to the updated format described in this document.
SDK Configuration Options
The behavior of the Embrace Unity SDK can be customized through the same list of configuration options as the Android and iOS SDKs.
Configuration options can be accessed in the Configurations tab of the Settings window. This window can be opened through the top-level menu Tools > Embrace > Settings or by clicking on the Customize SDK Configuration button from the Getting Started window.
Creating and Editing Configurations
Some applications have complex build pipelines. For example, it's common practice for a development team to work in a "Dev" environment, then push their changes to a "Staging" when features are complete and ready to be tested, and finally released to a "Production" upon final approval. In such cases it may be beneficial define different configuration options for each environment. The Embrace SDK supports this this type of workflow through the Configurations list available in the Settings window.
Using this list you can easily add, rename, or remove configurations as needed. Each configuration will create an Android and iOS configuration file stored in the Embrace data directory. The names of these configurations are only used to identify them in the Unity editor, and will not be replicated in the Embrace dashboard.
You can select and edit each configuration by clicking on the toggle to the left of each list item in the Settings window, or by selecting a configuration from the Getting Started window.
NOTE: Most of the time users will not see the creation of configuration data when the Configurations list is edited. However, if you happen to peek in the Configurations folder, you'll notice that upon defining a configuration objects are created with a GUID-based name. They will get automatically renamed to match user input once the Update Configurations button is pressed, or if the Settings window loses focus. See the reference images above for an example.
Specifying Configurations At Build Time
The Embrace SDK also supports specifying a configuration at build-time through the use of environment variables defined at the OS level. This feature can enable a CI/CD pipeline to define which configuration to build with. We support the follwing definitions:
- Define this variable with the index number of an existing Embrace configuration.
Out-of-range indices will result in build failure.
- Define this variable with the name of an existing configuration (e.g. "Dev", "Staging", or "Prod");
We only support the use of a single environment variable to specify an Embrace configuration. Please be aware that defining both variables at build-time will result in a failed build.
For example, let's assume the following configurations are defined ("Dev", "Staging", and "Prod"), and the CI/CD build-time target environment should be "Staging".
If you'd like to specify "Staging" via it's index, you would define the following:
$ export EMBRACE_ENVIRONMENTS_INDEX=1
C:\> SET EMBRACE_ENVIRONMENTS_INDEX=1
Alternatively, to specify by the name "Staging":
$ export EMBRACE_ENVIRONMENTS_NAME=Staging
C:\> SET EMBRACE_ENVIRONMENTS_NAME=Staging
Users will notice that both default and custom configurations already have some fields defined upon creation. These fields correspond to the defaults specified for Android and iOS. At build time, configuration files are loaded and scanned for non-default settings, which are then output to an override configuration file for their specific platforms.
For example, in the
sdk_config.session sub-element of the Android configuration, if the
async_end flag is set to
max_session_seconds is set to
120 the output
embrace-config.json file will only feature those fields as overrides since they are overriding default settings. Likewise, in the iOS configuration the
STARTUP_MOMENT_SCREENSHOT_ENABLED fields were modified with non-default values, and are therefore the only settings included in the
api_token fields are always included.
The Unity Embrace SDK will store configuration data in the
Assets/Embrace directory of your project. This directory can be customized in the Settings window under the General tab. Specify a new directory in the Embrace Data Directory field. Note that this path will remain relative to your project's
Assets folder. This is a necessary constraint since we depend on the Unity's
AssetDatabase utility to manage user-generated configuration files.