App Settings

You can use App Settings to define a set of variables that can be referenced from within other parts of the app definition. For example, you can reference defined app settings variables from within definitions for properties such as command headers, workflow conditions, workflow actions, and widget URLs.

If app settings are defined, the Kustomer platform will automatically generate an apps settings page UI to appear in the Kustomer App Directory once the app is installed.

If Custom Settings Pages for the app are defined, then the custom settings will override the default app settings in the UI.

App Settings format in the app definition

The app settings property takes definitions for variable values in settings objects inside settings categories. Within each category, the key of each settings object is the id of the setting.

Each settings category takes settings objects that can define additional settings properties for each settings object such as type, default value, and setting description.

Note: Use the default category by convention if you define only a single settings category for the app.

settings definition example

The defined settings property below contains one category: default

The default category contains two settings objects: authToken and subdomain.

Note: When you define settings, you will also need to define the i18n property to provide Internationalization for the text strings to display in the app settings page UI. We've included a corresponding sample i18n property definition below.

{
  "app": "standardecomm",
  "version": "0.0.1",
  "title": "Standard E-comm",
  "settings": {
    "default": {
      "authToken": {
        "type": "secret",
        "defaultValue": "",
        "required": true
      },
      "subdomain": {
        "type": "string",
        "defaultValue": "",
        "description": "The subdomain field that will be included in the API when we make a request"
      }
    }
  },
  "i18n": {
    "en_us": {
      "standardecomm.settings.page.title": "Standard E-comm", 
      "standardecomm.settings.page.description": "Configure settings for your Standard E-comm app",
      "standardecomm.settings.path.default.authToken.description": "An auth token for accessing the Standard E-comm service",
      "standardecomm.settings.path.default.authToken.displayName": "Auth Token",
      "standardecomm.settings.path.default.subdomain.description": "The subdomain of of your store on the Standard E-comm site",
      "standardecomm.settings.path.default.subdomain.displayName": "Subdomain"
    }
  }      
}

App Settings property descriptions

The basic definition properties for each settings category and their descriptions are listed below:

Settings categories

The settings category. Within a category, the key of a settings object is the id of the setting.

Notes:

• Use the default category by convention if you define only a single settings category for the app.
• If you define an authToken setting in the default category, you would define the setting as settings.default.authToken, as shown in the example below.

Example of default category definition with settings objects authToken and subdomain:

"default": {
      "authToken": {
        "type": "secret",
        "defaultValue": "",
        "required": true
      },
      "subdomain": {
        "type": "string",
        "defaultValue": "",
        "description": "The subdomain field that will be included in the API when we make a request"
      }

Settings objects

Settings categories contain settings objects. The key of settings object is the id of the setting.

Example of subdomain category definition with values for type, defaultValue, and description:

 "subdomain": {
        "type": "string",
        "defaultValue": "",
        "description": "The subdomain field that will be included in the API when we make a request"
      }

type

Required. Settings can have a string, boolean, number or secret type. Settings for secret are string values that are hidden from the user and can only be referenced within Commands or Workflow Actions.

Example: "type": "secret"

defaultValue

Required. Settings must explicitly specify a default value. You can choose to make the default an empty string or null if no default value is desired.

Example: "defaultValue": ""

description

Description of the setting. The description should provide a meaningful and human-readable explanation of the setting. Supports Markdown formatting.

Example: "description": "The subdomain field that will be included in the API when we make a request"

Internationalization for settings page text

When a user installs your app, the Kustomer platform automatically generates an app settings page for the UI based on the defined app settings. It's important to provide internationalized text strings for the app settings page. Provide text strings for the display names and the descriptions for the page and each settings object.

See Internationalization for more information.

Example:

"i18n": {
      "en_us": {
        "standardecomm.settings.page.title": "Standard E-comm",
        "standardecomm.settings.page.description": "Configure settings for your Standard E-comm app",
        "standardecomm.settings.path.default.authToken.description": "An auth token for accessing the Standard E-comm service",
        "standardecomm.settings.path.default.authToken.displayName": "Auth Token",
        "standardecomm.settings.path.default.subdomain.description": "The subdomain of your store on Standard E-comm",
        "standardecomm.settings.path.default.subdomain.displayName": "Subdomain"
      } 
    }

App Settings and Custom Settings Pages

If Custom Settings Pages for the app are defined, then the custom settings will override the default app settings in the UI. In this case, the Kustomer platform will not auto-generate a page for apps settings.

You can still edit and update app settings using the Cards SDK to access the API.

For more information, see the following Kustomer API endpoints: Get a Setting and Update a Setting.

📘

Note

When accessed through the API, secrets will return a placeholder string on GETs and not be readable.