Bixby Developer Center

There are two ways to store configuration information for your capsules, such as endpoint URIs, API keys, permission scopes, environment modes, or any other configuration data that you'd like to be able to change without editing capsule code:

• The capsule.properties file within your capsule itself.
• The Configuration & Secrets tab of your capsule settings page in the Developer Console section of the Bixby Developer Center.

Secrets are sensitive information that should not be stored in code and might need to be updated frequently, such as API keys or other authentication details. By entering these in the Secrets section of the Bixby Developer Center, they will be securely encrypted end-to-end, and will even appear obfuscated in the Developer Center's UI. Secrets can be updated at any time.

Static, non-sensitive information that isn't likely to change often should be defined in the capsule.properties file. This could include endpoint URIs, permission scopes, and feature gates.

By setting dynamic properties in the Configurations section of the Bixby Developer Center, you can change property values without editing capsule code. If you define capsule properties in the Developer Center with the same names as properties in the capsule.properties file, the dynamic values will override the static ones in the file. Delete these dynamic properties to return to the values defined in the file.

Capsule Properties File

Use the capsule.properties file to store configuration properties related to your capsule, such as endpoints, scopes, or whether to use test or production configuration properties. This file is for properties that you don't expect to change very often, if at all. Properties that are likely to change should be handled through the Configuration & Secrets screen of the Bixby Developer Center. (You can override any property defined in this file by entering a new value for it in the Configuration screen.)

This file use a simple INI-like format:

key=value
group.key=value

Configuration Mode

You can set the configuration mode for your capsule using capsule.config.mode.

You can set properties for specific configuration modes, which are helpful when you want to use your capsule in different environments.

capsule.config.mode=default

Capsule Properties

You can set properties for each mode using this format:

config.%mode%.%propertyKey%=%propertyValue%

Use the default mode for any fallback property values:

config.default.my.property.key=myValue 123

Capsule properties are treated as strings, so ensure that you cast them to right type. Do not include empty strings, as they are then surrounded by quotes ("""").

Toggle Properties and Content

You can toggle individual capsule properties using this format:

config.default.toppicks=false

You can toggle content from a capsule using this format:

capsule.enabled=false

Configuration & Secrets

To set configuration properties and secrets dynamically through the web interface:

1. Open the Developer Console.
2. Select the capsule for which you want to edit configuration values or secrets.
3. Select the Settings tab.

3. Click the + Add button to add a new key/value pair to either the Configuration section or the Secrets section. This will display fields to enter a new name and value, as well as a + Add button to add more rows. When you're finished, click Save & Apply. The new keys will immediately be used by all deployed versions of the capsule.
4. Click Edit to edit existing key/value pairs.
5. Click the X to the right of any key/value pair that appears on hover to delete it.

You can provide different values for properties and secrets in development and production modes by selecting Development or Production in the Mode menu. You can learn more about when these modes are used in the Property Precedence section.

Property Precedence

When Bixby looks for a property value, it normally follows this precedence:

1. Properties defined in the Configuration & Secrets UI Dev mode, when applicable.
2. Properties defined in the Configuration & Secrets UI Prod mode, when applicable.
3. Properties defined in the currently active configuration mode in capsule.properties.
4. Properties defined in the default configuration mode in capsule.properties.

However, the mode that Bixby starts looking in is dependent on the following:

• If you are using a private submission as a revision override (either in the Simulator or while on-device testing), Bixby follows steps 1-4.
• If you are testing synced capsules in the Simulator, Bixby follows steps 1-4.
• If you are using a public submission as a revision override (either in the Simulator or while on-device testing), Bixby follows steps 2-4 (and ignores Dev mode).

For example, if you define config.sport=baseball in the properties file and then use the Configuration & Secrets screen to set sport to cricket, calling config.get('sport') from the JavaScript API (see Reading Properties & Secrets below) will return cricket, not baseball. The definition in the UI screen has a higher precedence than the definition in capsule.properties.

Reading Properties & Secrets

To access configuration properties, use the config.get() JavaScript method. To access secrets, use the secrets.get() JavaScript method.

const configValue = config.get('myConfigKey')
const secretValue = secret.get('mySecretKey')

Secrets and configuration properties are entirely separate from each other: config.get('key') and secret.get('key') can yield different values. The configuration property named key and the secret named key are separate.

Secret keys are also used for OAuth Authorization and can be specified with the client-secret-key key.

authorization {
  user {
    oauth2-authorization-code (providerId) {
      authorize-endpoint (https://example.com/login/v3/oauth)
      client-id (mybixbyclient)
      client-secret-key (secretkey)
      token-endpoint (MyToken.js::tokenEndpoint)
    }
  }
}

In this example, secretkey is the name of the secret property defined in the Configuration & Secrets screen that contains the authorization value, similar to secret.get('secretkey') in JavaScript.