Users are guided through the SmartApp installation process via configuration screens.
The configuration process provides user with basic information about the SmartApp, and requests any information or access to devices the SmartApp may need.
This process triggers the
CONFIGURATION lifecycle event.
Your app must handle the configuration lifecycle by:
- Providing basic information about the app itself.
- Providing the configuration data that represents the information needed from the user to install your app.
#Configuration Request Basics
During the configuration lifecycle, your app will receive a request with a JSON payload with a lifecycle of
"CONFIGURATION" and a
The configuration lifecycle has two phases: INITIALIZE and PAGE, discussed in detail below.
The contents of
configurationData will vary depending on the phase and any configuration inputs already entered by the user.
The general flow of the configuration phase is shown below (for a two-page configuration process):
INITIALIZE phase occurs at the beginning of the configuration lifecycle, as the user begins the installation and configuration process.
During the INITIALIZE phase, your SmartApp will receive a request with a JSON payload:
Your app must respond with JSON specifying basic information about your app, including the permissions required to configure it, and the ID of the first configuration page.
An example response for a SmartApp that requires configuration access to a user's devices and the ability to gather scheduling data might look like:
id must be unique among any other settings as defined below.
You should specify the permissions your app will need during the install process. See Authorization and Permissions for more information.
All information the user may configure for your SmartApp is organized in pages. A SmartApp may have one to many pages.
For each defined page, the
PAGE phase of a configuration lifecycle will occur.
During the PAGE phase, your app will receive a request with a JSON payload like:
As the user progresses through pages, each page will generate a configuration lifecycle event, and the requested page can be found in the
configurationData object on the request. Your SmartApp is responsible for responding with the configuration data for the requested page.
A page must specify
complete: true to indicate it is the last page in the configuration process.
#Sections and settings
Each page is composed of one or more sections, each containing a settings array with one or more setting(s).
An example response to a configuration lifecycle request for a single-page configuration would look like:
If your app requires multiple configuration pages, each response to the configuration lifecycle should specify
complete as necessary. A configuration request will be made to your app for each page, based upon the
An example response to a configuration lifecycle request for the first page of a two-page configuration would look like:
Upon advancing to the second page, another configuration lifecycle event occurs, and our app would respond to this request:
The last page must specify
complete: true to indicate that the SmartApp configuration will be completed on this page.
Each section is composed of one or more settings, which define the type of information to gather from the user (or, in the case of the paragraph setting, display-only information).
The type of setting is denoted by the
type field in the setting object.
settings array must be inside a
Use a DEVICE setting when your app requires the user to select one or more devices.
Devices that match the specified
capabilities will be eligible for selection.
If multiple values are specified, only devices matching all requested capabilities will be eligible.
When the user subscribes to a Capability and selects the device(s), in the SmartApp, while receiving the device events, the type of the value will correspond to the attribute type defined in the Capability.
Your app should specify the appropriate permissions it requires of the device via the
The available permission values are:
|"r"||Read access. The app may read device attributes, but not execute commands on the device.|
|"x"||Execute access. The app may execute command on the device.|
|"w"||Write access. The app may update data about the device itself.|
Permissions are independent (i.e., execute permission does not also grant read permission); multiple permissions may be specified.
TEXT setting when your app requires free-form text input.
BOOLEAN setting when your app requires a true/false input.
The ENUM setting can be used to allow the user to select one or more options from a predefined list.
An ENUM setting may also group a set of its options by specifying
Use the LINK setting when your app needs to provide a link to an external resource.
The PAGE setting allows the user to jump to a specific configuration page.
The IMAGE setting allows for the display of an image. Image width and height are automatically controlled using CSS styles for a responsive design.
Use the ICON setting to display an icon.
Use the TIME setting to allow the user to input a specified time.
Use the PARAGRAPH setting to display some text to the user.
Use the EMAIL setting to request an email address from the user.
Use the DECIMAL setting to request a decimal value from the user.
Use the NUMBER setting to request a number value from the user.
Use the PHONE setting to request a phone number from the user.
Use the OAUTH setting when your app requires OAuth authentication with a third-party service.
browseroption can be enabled if you prefer to open a browser window to execute the authentication flow, giving users access to their stored sessions.
urlTemplateis a URL template that will be used as the callback URL during the OAuth flow with the third-party. The OAuth callback parameter must have the URL encoded value of the OAuth callback url for SmartThings Cloud:
All settings values, regardless of their value type, are sent as strings.
If your authorization scenario requires you to intercept and append additional data to the callback URL, you must not modify or remove the
state parameter. For your SmartApp to receive additional linking data, you may include additional parameters, ensuring that
state remains intact. This allows SmartThings to route your additional parameter data back to your SmartApp. These parameters can have any name, excluding
state. It is recommended to
Base64Encode the parameter values.
state is an opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. See the OAuth 2.0 specification.
Upon receiving your OAuth callback data event, your SmartApp can parse the extra data parameters from the
urlPath property to retrieve these parameters from the callback.
#Getting settings values during configuration
All input values for previously completed pages are available on the request.
Each setting value is stored in the
config object of the
The field name is the setting ID.
All settings values, regardless of their value type, are sent as strings.
Consider the case of a two-page configuration, where the user has entered in a value for setting on the first page with ID "minutes". When the user advances to the second page, the request to the SmartApp would look like:
Note that all config entries are stored as arrays; in the case of single-entry settings this will be a one-item array. Multiple-entry settings (e.g., selecting multiple devices for a single setting) will contain all configured inputs.
#Configuration value types
Configuration values may be one of two types, as denoted by the
Each value type is associated with a config object for that type as summarized in the following table:
|Value type||Config name|
Any non-device setting type entered by the user will be returned as a
STRING type, with a
stringConfig object containing the value entered.
Recall that all non-device setting inputs, regardless of their type, are stored as strings.
Devices selected by the user will be returned as a
DEVICE type, with a
deviceConfig object containing information about the device selected:
In some circumstances, the presence of, or available options for, one setting may depend on the value chosen for another setting. In these cases, your app can inspect the value(s) entered for a given setting and return the appropriate configuration data given the previously-entered value.
Dependent settings must be on separate pages.
Consider the scenario for a SmartApp that turns a light on when a chosen triggering event occurs. For example, the user may wish to turn the light on when a contact sensor is opened, or when motion is detected.
The following Node.js example shows how this may be accomplished.