_smart_app_d_.smartapp.md

Reference › SmartApp

SmartApp

An instance of the SmartApp class is created to handle lifecycle events for WEBHOOK_SMART_APP, LAMBDA_SMART_APP, and API_ONLY apps. Options can either be passed in as parameters to the constructor, for example:

import {SmartApp} from '@smartthings/smartapp'
...
const smartApp = new SmartApp({
    appId: 'xxx',
    disableCustomDisplayName: true
})

or set with individual chained configuration method calls, for example:

const smartApp = new SmartAll()
    .appId('xxx')
    .disableCustomDisplayName()

Constructor

+ new SmartApp(options?: SmartAppOptions): SmartApp

Create a SmartApp instance

Parameters:

Name	Type	Description
options?	SmartAppOptions	configuration object defining SmartApp options

Returns: SmartApp

Methods

• apiUrl
• appId
• clientId
• clientSecret
• configureI18n
• configureLogger
• contextStore
• defaultDeviceCommandHandler
• defaultPage
• defaultScheduledEventHandler
• deviceCommand
• deviceCommandHandler
• disableCustomDisplayName
• disableRemoveApp
• enableEventLogging
• executeHandler
• firstPageId
• handleHttpCallback
• handleHttpCallbackUnverified
• handleLambdaCallback
• handleMockCallback
• handleOAuthCallback
• initialized
• installed
• keyApiHost
• oauthHandler
• page
• permissions
• publicKey
• redirectUri
• refreshUrl
• scheduledEventHandler
• subscribedDeviceEventHandler
• subscribedDeviceHealthEventHandler
• subscribedDeviceLifecycleEventHandler
• subscribedEventHandler
• subscribedHubHealthEventHandler
• subscribedModeEventHandler
• subscribedSceneLifecycleEventHandler
• subscribedSecurityArmStateEventHandler
• unhandledRejectionHandler
• uninstalled
• updated
• withContext

apiUrl

▸ apiUrl(url: string): SmartApp

Specify an alternate base URL for SmartThings API calls. This value is only necessary for testing new API versions or non-production environments.

Parameters:

Name	Type	Description
url	string	base URL of the alternate API

Returns: SmartApp

---

appId

▸ appId(id: string): SmartApp

Set the app that this SmartApp object is implementing. This field is necessary for any app that requires permissions in addition to those implied by the app configuration settings.

Parameters:

Name	Type	Description
id	string	either the App.appId or App.appName field of your SmartApp

Returns: SmartApp

---

clientId

▸ clientId(id: string): SmartApp

Set the client id, which together with the client secret, enables apps that make proactive calls to the SmartThings API to refresh their access tokens. Does not need to be set for apps that only respond to lifecycle events because those event requests contain valid tokens.

Parameters:

Name	Type	Description
id	string	the clientId that was generated when the App was created

Returns: SmartApp

---

clientSecret

▸ clientSecret(secret: string): SmartApp

Set the client secret, which together with the client id, enables apps that make proactive calls to the SmartThings API to refresh their access tokens. Does not need to be set for apps that only respond to lifecycle events because those event requests contain valid tokens.

Parameters:

Name	Type	Description
secret	string	the clientSecret that was generated when the App was created

Returns: SmartApp

---

configureI18n

▸ configureI18n(options?: ConfigurationOptions): SmartApp

Configure the i18n localization framework used to translate app installation pages. The most commonly used option is {updateFiles: true} which will automatically add keys to the localization file for new configuration page settings. The use of the i18n framework is recommended even if you are not planning to support multiple languages in your app because it nicely separates user-visible text from the app logic, allowing that text to be changed without changing the app code itself.

Parameters:

Name	Type	Description
options?	ConfigurationOptions	settings of the i18n localization module

Returns: SmartApp

---

configureLogger

▸ configureLogger(logger: Logger): SmartApp

Override the default Winston event and error logger. You may want to do this to integrate with your logging infrastructure. The default logger writes to the console.

Parameters:

Name	Type	Description
logger	Logger	your logging implementation

Returns: SmartApp

---

contextStore

▸ contextStore(contextStore: ContextStore): SmartApp

Sets the context store implementation for saving and retrieving installed app context. A context store is required for apps that make SmartThings API calls in response to external trigger and conditions. Apps that only response to lifecycle events from SmartThings do not require a context store because the installed app context is provided in the call.

Parameters:

Name	Type	Description
contextStore	ContextStore	a service implementing the context store interface

Returns: SmartApp

---

defaultDeviceCommandHandler

▸ defaultDeviceCommandHandler(callback: function): SmartApp

Defines a handler to be called for any device command event that does not have a handler defined for that specific command. The default implementation of this handler simply logs a message about the missing command handler. Note that only C2C connector SmartApps that create devices will receive command events.

Parameters:

▪ callback: function

▸ (context: SmartAppContext, deviceId: string, cmd: DeviceCommand): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
deviceId	string
cmd	DeviceCommand

Returns: SmartApp

---

defaultPage

▸ defaultPage(callback: function): SmartApp

Defines a handler that is called for any configuration page that does not have a specific page handler mapped to that page id. Default page handlers are typically used when an app has a variable number of configuration pages. For example, an app that has a separate configuration page for each room of a location.

Parameters:

▪ callback: function

▸ (context: SmartAppContext, page: Page, configData?: InstalledAppConfiguration): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
page	Page
configData?	InstalledAppConfiguration

Returns: SmartApp

---

defaultScheduledEventHandler

▸ defaultScheduledEventHandler(callback: function): SmartApp

Defines a handler to be called for any scheduled event that does not have a handler defined for that specific event.

Parameters:

▪ callback: function

▸ (context: SmartAppContext, eventData: TimerEvent): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
eventData	TimerEvent

Returns: SmartApp

---

deviceCommand

▸ deviceCommand(command: string, callback: function): SmartApp

Defines a handler for a specific device command.

Parameters:

▪ command: string

the command path in the form [component]/capability/command. If the component is not specified then the handler will be called for all components.

▪ callback: function

the handler called when the specified command is received

▸ (context: SmartAppContext, deviceId: string, cmd: DeviceCommand, eventTime?: string): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
deviceId	string
cmd	DeviceCommand
eventTime?	string

Returns: SmartApp

---

deviceCommandHandler

▸ deviceCommandHandler(callback: function): SmartApp

Defines a single command handler for all device commands. Its use should be exclusive with the deviceCommand() method that defines handlers for specific commands because those handlers will not be called if a handler is defined here. To define a handler that's called only when no specific device command handler exists use defaultDeviceCommandHandler

Parameters:

▪ callback: function

▸ (context: SmartAppContext, deviceId: string, eventData: DeviceCommandsEvent, eventTime?: string): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
deviceId	string
eventData	DeviceCommandsEvent
eventTime?	string

Returns: SmartApp

---

disableCustomDisplayName

▸ disableCustomDisplayName(value: boolean): SmartApp

Disable the ability for users to rename the installed app instance in the configuration page. This behavior may be desirable for singleton apps that can only be installed once per location. Apps that can be installed multiple times per location should not disable renaming, or the result will be multiple apps with the same name.

Parameters:

Name	Type
value	boolean

Returns: SmartApp

---

disableRemoveApp

▸ disableRemoveApp(value: boolean): SmartApp

Disable the button that allows users to remove the app from the configuration page. Apps can still be removed using the delete menu options.

Parameters:

Name	Type
value	boolean

Returns: SmartApp

---

enableEventLogging

▸ enableEventLogging(jsonSpace?: number, enableEvents?: boolean): SmartApp

Turns on the logging of lifecycle events and responses.

Parameters:

Name	Type	Description
jsonSpace?	number	the number of spaces to use for indentation in pretty-printed output. Setting this value to zero disables pretty printing
enableEvents?	boolean	whether or not to enable logging. Defaults to true

Returns: SmartApp

---

executeHandler

▸ executeHandler(callback: function): SmartApp

Defines a handler for EXECUTE lifecycle events

Parameters:

▪ callback: function

▸ (context: SmartAppContext, executeData: ExecuteData): Promise‹any›

Parameters:

Name	Type
context	SmartAppContext
executeData	ExecuteData

Returns: SmartApp

---

firstPageId

▸ firstPageId(id: string): SmartApp

Sets the initial configuration page to be rendered when an app is installed or updated. If not specified then the first page defined will be rendered.

Parameters:

Name	Type
id	string

Returns: SmartApp

---

handleHttpCallback

▸ handleHttpCallback(request: WebHookRequest, response: WebHookResponse): Promise‹void›

To be called by the web server to handle lifecycle events from WEBHOOK_SMART_APPs

Parameters:

Name	Type
request	WebHookRequest
response	WebHookResponse

Returns: Promise‹void›

---

handleHttpCallbackUnverified

▸ handleHttpCallbackUnverified(request: WebHookRequest, response: WebHookResponse): Promise‹void›

Bypasses event signature verification of WEBHOOK_SMART_APP requests. This method can be useful for testing apps with the APP_RSA signature type but is not needed for apps with the ST_PADLOCK signature type (which is now the default). Do not use in production apps.

Parameters:

Name	Type
request	WebHookRequest
response	WebHookResponse

Returns: Promise‹void›

---

handleLambdaCallback

▸ handleLambdaCallback(event: any, context: Context, callback: function): void

To be called by AWS Lambda functions to handle LAMBDA_APP lifecycle events.

Parameters:

▪ event: any

▪ context: Context

▪ callback: function

▸ (): any

Returns: void

---

handleMockCallback

▸ handleMockCallback(body: any): Promise‹void›

To be called by test scripts

Parameters:

Name	Type
body	any

Returns: Promise‹void›

---

handleOAuthCallback

▸ handleOAuthCallback(request: WebHookRequest): Promise‹ContextRecord›

To be called by the web server of an API access app when it receives an OAuth2 callback. Redeems the code for access and refresh tokens.

Parameters:

Name	Type
request	WebHookRequest

Returns: Promise‹ContextRecord›

---

initialized

▸ initialized(callback: function): SmartApp

Defines a handler to be called before configuration the first time a SmartApp is installed.

Parameters:

▪ callback: function

▸ (context: SmartAppContext, initialization: Initialization, configData: ConfigurationData): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
initialization	Initialization
configData	ConfigurationData

Returns: SmartApp

---

installed

▸ installed(callback: function): SmartApp

Defines a handler to be called after configuration the first time a SmartApp is installed. If not specified then the updated() handler will be called on the initial installation as well as updates.

Parameters:

▪ callback: function

▸ (context: SmartAppContext, installData: InstallData): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
installData	InstallData

Returns: SmartApp

---

keyApiHost

▸ keyApiHost(url: string): SmartApp

Specify an alternate OAuth2 refresh URL for API access apps. This value is only necessary for testing new API versions or non-production environments.

Parameters:

Name	Type
url	string

Returns: SmartApp

---

oauthHandler

▸ oauthHandler(callback: function): SmartApp

Defines a handler to be called when the user completes the OAuth2 sign in process to a third party cloud that has been initiated from an app installation page.

Parameters:

▪ callback: function

▸ (): HandlerResponse

Returns: SmartApp

---

page

▸ page(id: string, callback: function): SmartApp

Defines a configuration page that is displayed during app installation and update. You can create as many pages as needed to satisfy your configuration needs. See the documentation on how to design pages for your automation.

Parameters:

▪ id: string

▪ callback: function

▸ (context: SmartAppContext, page: Page, configData?: InstalledAppConfiguration): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
page	Page
configData?	InstalledAppConfiguration

Returns: SmartApp

---

permissions

▸ permissions(value: string | string[]): SmartApp

Specify the OAuth2 scopes explicitly required by this app. For example `['r:devices:', and 'x:devices:'] to be able to read and control all devices in the location. You do not have to provide this list for devices selected by the user in configuration settings.

If permissions are specified, appId is also required.

Parameters:

Name	Type
value	string | string[]

Returns: SmartApp

---

publicKey

▸ publicKey(value: string): SmartApp

Set the public key to be used for signature verification of lifecycle event calls. Not necessary for apps that use ST_PADLOCK signatures.

Parameters:

Name	Type
value	string

Returns: SmartApp

---

redirectUri

▸ redirectUri(uri: string): SmartApp

Set the OAuth2 redirect uri used for API Access integrations to SmartThings

Parameters:

Name	Type
uri	string

Returns: SmartApp

---

refreshUrl

▸ refreshUrl(url: string): SmartApp

Specify an alternate OAuth2 refresh URL for API Access apps. This value is only necessary for testing new API versions or non-production environments.

Parameters:

Name	Type
url	string

Returns: SmartApp

---

scheduledEventHandler

▸ scheduledEventHandler(name: string, callback: function): SmartApp

Defines a handler for scheduled events. The name corresponds the the name specified when the event is scheduled by the context.api.schedules.create() call or any of its other variants. There can be multiple scheduled event handlers in one app.

Parameters:

▪ name: string

the name used when the event to be handled was scheduled

▪ callback: function

the handler to be called with the event

▸ (context: SmartAppContext, eventData: TimerEvent, eventTime?: string): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
eventData	TimerEvent
eventTime?	string

Returns: SmartApp

---

subscribedDeviceEventHandler

▸ subscribedDeviceEventHandler(name: string, callback: function): SmartApp

Defines a handler for device event subscriptions. Device events occur whenever one of the attributes of a device changes state, such as when a switch turns on or off. The name corresponds to the name specified when the subscription is created with the context.api.subscriptions.subscribeToDevices() call. There can be multiple subscribed device event handlers in one app.

Parameters:

▪ name: string

the name used when the subscription was created

▪ callback: function

the handler to be called with the event

▸ (context: SmartAppContext, deviceEvent: DeviceEvent, eventTime?: string): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
deviceEvent	DeviceEvent
eventTime?	string

Returns: SmartApp

---

subscribedDeviceHealthEventHandler

▸ subscribedDeviceHealthEventHandler(name: string, callback: function): SmartApp

Defines a handler for device health event subscriptions. Device health events occur whenever a device goes online or offline, or fails for some other reason. The name corresponds to the name specified when the subscription is created by the context.api.subscriptions.subscribeToDeviceHealth(). There can only be one device health event handler for an app.

Parameters:

▪ name: string

the name used when the subscription was created

▪ callback: function

the handler to be called with the event

▸ (context: SmartAppContext, eventData: DeviceHealthEvent, eventTime?: string): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
eventData	DeviceHealthEvent
eventTime?	string

Returns: SmartApp

---

subscribedDeviceLifecycleEventHandler

▸ subscribedDeviceLifecycleEventHandler(name: string, callback: function): SmartApp

Defines a handler for device lifecycle event subscriptions. Device lifecycle events occur whenever a device is created, deleted, updated, or moved to another room. The name argument corresponds to the name specified when the subscription is created by the context.api.subscriptions.subscribeToDeviceHealth() call. There can only be one device lifecycle event handler for an app.

Parameters:

▪ name: string

the name used when the subscription was created

▪ callback: function

the handler to be called with the event

▸ (context: SmartAppContext, eventData: DeviceLifecycleEvent, eventTime?: string): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
eventData	DeviceLifecycleEvent
eventTime?	string

Returns: SmartApp

---

subscribedEventHandler

▸ subscribedEventHandler(name: string, callback: function, type?: EventType): SmartApp

Defines a handler for any subscribed event. If the type of event is not specified it defaults to DEVICE_EVENT.

Parameters:

▪ name: string

the name used when the subscription was created

▪ callback: function

the handler to be called with the event

▸ (context: SmartAppContext, eventData: DeviceEvent, eventTime: string): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
eventData	DeviceEvent
eventTime	string

▪Optional type: EventType

the type of event being subscribed to

Returns: SmartApp

---

subscribedHubHealthEventHandler

▸ subscribedHubHealthEventHandler(name: string, callback: function): SmartApp

Defines a handler for hub health event subscriptions. Hub health events occur whenever a hub goes online or offline, or fails for some other reason. The name argument corresponds to the name specified when the subscription is created by the context.api.subscriptions.subscribeToHubHealth() call. There can only be one hub health event handler for an app.

Parameters:

▪ name: string

the name used when the subscription was created

▪ callback: function

the handler to be called with the event

▸ (context: SmartAppContext, eventData: HubHealthEvent, eventTime?: string): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
eventData	HubHealthEvent
eventTime?	string

Returns: SmartApp

---

subscribedModeEventHandler

▸ subscribedModeEventHandler(name: string, callback: function): SmartApp

Defines a handler for location mode change subscriptions. The location mode can be changed manually by the user or automatically with an automation or another SmartApp. The name argument corresponds to the name specified when the subscription is created by the context.api.subscriptions.subscribeToModeChange() call. There can only be one mode change event handler for an app.

Parameters:

▪ name: string

the name used when the subscription was created

▪ callback: function

the handler to be called with the event

▸ (context: SmartAppContext, eventData: ModeEvent, eventTime?: string): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
eventData	ModeEvent
eventTime?	string

Returns: SmartApp

---

subscribedSceneLifecycleEventHandler

▸ subscribedSceneLifecycleEventHandler(name: string, callback: function): SmartApp

Defines a handler for scene lifecycle event subscriptions. Scene lifecycle events occur whenever a scene is created, deleted, or updated. The name argument corresponds the the name specified when the subscription is created by the context.api.subscriptions.subscribeToSceneLifecycle() call. There can only be one scene lifecycle event handler for an app.

Parameters:

▪ name: string

the name used when the subscription was created

▪ callback: function

the handler to be called with the event

▸ (context: SmartAppContext, eventData: SceneLifecycleEvent, eventTime?: string): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
eventData	SceneLifecycleEvent
eventTime?	string

Returns: SmartApp

---

subscribedSecurityArmStateEventHandler

▸ subscribedSecurityArmStateEventHandler(name: string, callback: function): SmartApp

Defines a handler for security system subscriptions. The handler will be called whenever the SmartThings Home Monitor application is armed or disarmed. The name argument corresponds to the name specified when the subscription is created by the context.api.subscriptions.subscribeToSecuritySystem() call. There can only be one security system event handler for an app.

Parameters:

▪ name: string

the name used when the subscription was created

▪ callback: function

the handler to be called with the event

▸ (context: SmartAppContext, eventData: SecurityArmStateEvent, eventTime?: string): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
eventData	SecurityArmStateEvent
eventTime?	string

Returns: SmartApp

---

unhandledRejectionHandler

▸ unhandledRejectionHandler(callback: function): SmartApp

Specify a function to be call if an unhandled rejection is encountered. The default handler logs the stack trace of the error

Parameters:

▪ callback: function

▸ (reason: Error): void

Parameters:

Name	Type
reason	Error

Returns: SmartApp

---

uninstalled

▸ uninstalled(callback: function): SmartApp

Defines a handler to be called when an instance of this app is uninstalled

Parameters:

▪ callback: function

▸ (context: SmartAppContext, uninstallData: UninstallData): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
uninstallData	UninstallData

Returns: SmartApp

---

updated

▸ updated(callback: function): SmartApp

Defines a handler to be called whenever the app configuration is updated by the user. If no separate installed() handler is defined, then this handler will also be called the first time the app is installed

Parameters:

▪ callback: function

▸ (context: SmartAppContext, updateData: UpdateData): HandlerResponse

Parameters:

Name	Type
context	SmartAppContext
updateData	UpdateData

Returns: SmartApp

---

withContext

▸ withContext(installedAppIdOrObject: string | ContextRecord): Promise‹SmartAppContext›

Returns a context object corresponding to the specified installedAppId or context record. If a context record is supplied, then the resulting SmartApp context is constructed from its properties. If an installed app UUID is specified, then the context for that installed instance will be read from the context store.

Parameters:

Name	Type	Description
installedAppIdOrObject	string | ContextRecord	either an installed app uuid or an object specifying the installed app id along with the auth and refresh tokens for the installed instance.

Returns: Promise‹SmartAppContext›