How to design Pages in a SmartApp

We’ve been receiving some questions about Pages in SmartApps. “How do you make and design them?” And, even more importantly, “What are Pages?”

A Page is a screen that is presented to a SmartApp user for setting up and configuring devices and Automations.

SmartApp creation

Our quickstart guides for SmartApp describe how to create SmartApps. The steps can be summarized as follows:

SmartApp creation

Easy, right? But where are Pages implemented?

Page design is actually part of Step 3. When SmartApp installation begins, the SmartApp receives the CONFIGURATION lifecycle event from SmartThings Cloud. The SmartApp must then respond with JSON data that defines the appearance and contents of a Page in the SmartThings app. This Page is shown during a SmartApp installation or update.

Page creation

When a user chooses to install your SmartApp, the user will be guided through the installation process via configuration screens (Pages). These screens provide the user with basic information about the SmartApp, and request information and/or access to devices needed by the SmartApp.

The installation process triggers the CONFIGURATION lifecycle event in your SmartApp. Your SmartApp must handle the CONFIGURATION event in two phases:

  • Provide basic information about the SmartApp itself. (INITIALIZE phase)
  • Provide configuration data that represents the information the user must provide on Pages to install your SmartApp. (PAGE phase)

INITIALIZE Phase

During the INITIALIZE phase of the CONFIGURATION lifecycle event, your SmartApp receives a JSON request:

{
  "lifecycle": "CONFIGURATION",
  "executionId": "85f0047b-bb24-8eeb-da11-cb6e2f767322",
  "locale": "en",
  "version": "0.1.0",
  "ConfigurationData": {
    "InstalledAppId": "8a0dcdc9-1ab4-4c60-9de7-cb78f59a1121",
    "phase": "INITIALIZE",
    "pageId": "",
    "previousPageId": "",
    "config": {
    }
  },
  "settings": {}
}

In the response, you send JSON data that includes basic information about the SmartApp:

{
  "ConfigurationData": {
    "initialize": {
      "name": "On When Open/Off When Shut WebHook App",
      "description": "On When Open/Off When Shut WebHook App",
      "id": "app",
      "permissions": [
        "l:devices",
        "l:schedules"
      ],
      "firstPageId": "1"
    }
  }
}

PAGE Phase

In the PAGE phase, the SmartApp receives a JSON request:

{
  "lifecycle": "CONFIGURATION",
  "executionId": "85f0047b-bb24-8eeb-da11-cb6e2f767322",
  "locale": "en",
  "version": "0.1.0",
  "ConfigurationData": {
    "InstalledAppId": "8a0dcdc9-1ab4-4c60-9de7-cb78f59a1121",
    "phase": "PAGE",
    "pageId": "",
    "previousPageId": "",
    "config": {
    }
  },
  "settings": {}
}

Your SmartApp must respond with a JSON payload that describes the sections and settings for at least one Page. The components of a Page are explained in Page Components.

NOTE

Your SmartApp must define at least one Page in JSON format during the PAGE phase. Testing the INITIALIZE implementation without defining at least one Page will return a server error.

Define a Single Page

Below is an example of a JSON response that describes a single Page.

{
  "configurationData": {
    "page": {
      "pageId": "1",
      "name": "On When Open/Off When Shut WebHook App",
      "previousPageId": null,
      "complete": true,
      "sections": [
        {
          "name": "When this opens/closes...",
          "settings": [
            {
              "id": "contactSensor",
              "name": "Which contact sensor?",
              "description": "Tap to select",
              "type": "DEVICE",
              "required": true,
              "multiple": false,
              "capabilities": ["contactSensor"],
              "permissions": [ "r" ]
            }
          ]
        }
      ]
    }
  }
}

This payload consists of Page data, Page sections, and settings that correspond to each Page section. Read more details in Page Components.

The field ‘complete’ is a Boolean that indicates whether this Page is the last Page. If your SmartApp has only one Page, this field should be set to “true”.

Below is the page that is displayed.

 SmartApp single page


Multiple Pages

If your app requires multiple Pages for configuration, you must specify nextPageId, previousPageId, and complete in a series of responses to the CONFIGURATION lifecycle. Based on the values of nextPageId and previousPageId, a CONFIGURATION request will be made to your SmartApp for each Page.

An example response to a CONFIGURATION lifecycle request for the first Page of a multi-page configuration would look like the following:

{
  "configurationData": {
    "page": {
      "pageId": "1",
      "name": "On When Open/Off When Shut WebHook App",
      "nextPageId": "2",
      "previousPageId": null,
      "complete": false,
      "sections": [
        {
          "name": "When this opens/closes...",
          "settings": [
            {
              "id": "contactSensor",
              "name": "Which contact sensor?",
              "description": "Tap to set",
              "type": "DEVICE",
              "required": true,
              "multiple": false,
              "capabilities": ["contactSensor"],
              "permissions": [ "r" ]
            }
          ]
        }
      ]
    }
  }
}

Upon advancing to the second Page, another CONFIGURATION lifecycle event occurs, and your SmartApp would respond to this request as shown below.

For a two-page configuration, you must specify complete = “true” to indicate that the SmartApp configuration will be completed on this Page.

{
  "configurationData": {
    "page": {
      "pageId": "2",
      "nextPageId": null,
      "previousPageId": "1",
      "complete": true
      "sections": [
        {
          "name": "Turn on/off this light...",
          "settings": [
            {
              "id": "lightSwitch",
              "name": "Which switch?",
              "description": "Tap to set",
              "type": "DEVICE",
              "required": true,
              "multiple": false,
              "capabilities": ["switch"],
              "permissions": [ "r" ,"x"]
            }
          ]
        }
      ]
    }
  }
}

The type property in the settings object has the value “DEVICE”. This means that tapping this type of setting will take the user to a list of Connected Devices that have the same Capabilities. Since required is set to “true”, the user must choose one of the Connected Devices.

In the final section, we will discuss other possible values of ‘type’.

Below are the Pages corresponding to the above responses that are displayed in the SmartThings app:

Example Page 1

SmartApp multipage1

Example Page 2

SmartApp multipage2

Page Components

The picture below shows the components of a Page in a SmartApp. Each Page is composed of one or more sections, each containing a settings array with one or more setting(s).

 SmartApp Page components


These are the fields used to describe Pages, sections, and settings.

page object sections object settings object
  • pageId
  • name
  • nextPageId
  • previousPageId
  • complete
  • array of sections
  • name
  • array of settings
    • id
    • name
    • description
    • type

    There are many types of settings, and each type is associated with different fields. You can see the various setting types in the table below.

    Types of Page Settings

    SmartThings has provided a collection of Page settings for your convenience. They are summarized in the table below.


    Device Setting

      "settings": [
      {
        "id": "lightSwitch",
        "name": "Which switch?",
        "description": "Tap to set",
        "type": "DEVICE",
        "required": true,
        "multiple": false,
        "capabilities": ["switch"],
        "permissions": ["r","x"]
      }
    ]
    

    Below is the page that is displayed.

    SmartApp Page setting


    Text Setting

    "settings": [
      {
        "id": "myTextSetting",
        "name": "Enter some text",
        "description": "Tap to set",
        "type": "TEXT",
        "required": true,
        "defaultValue": "Some default value"
      }
    ]
    

    Below is the page that is displayed.

    SmartApp Page setting


    Boolean Setting

    "settings": [
      {
        "id": "myBooleanSetting",
        "name": "True or false?",
        "description": "Tap to set",
        "type": "BOOLEAN",
        "required": true,
        "defaultValue": "true"
      }
    ]
    

    Below is the page that is displayed.

    SmartApp Page setting


    Enum Setting

    "settings": [
      {
        "id": "myEnumSetting",
        "name": "Choose what applies",
        "description": "Tap to set",
        "type": "ENUM",
        "required": true,
        "multiple": true,
        "options": [
          {
            "id": "option-1",
            "name": "Option 1"
          },
          {
            "id": "option-2",
            "name": "Option 2"
          }
        ]
      }
    ]
    

    Below is the page that is displayed.

    SmartApp Page setting


    "settings": [
      {
        "id": "myLinkSetting",
        "name": "Visit the following link",
        "description": "Tap to visit",
        "type": "LINK",
        "url": "https://smartthings.developer.samsung.com"
      }
    ]
    

    Below is the page that is displayed.

    SmartApp Link setting


    Page Setting

    "settings": [
      {
        "id": "myPageSetting",
        "name": "Choose what applies",
        "description": "Tap to set",
        "type": "PAGE",
        "page": "1",
        }
    ]
    

    Below is the page that is displayed.

     SmartApp Page setting


    Image Setting

    "settings": [
      {
        "id": "myImageSetting",
        "name": "Show the image",
        "description": "Show the image",
        "type": "IMAGE",
        "height": "400",
        "width": "206",
        "image":"https://smartthings.developer.samsung.com/docs/how-to/img/img-sample.jpg"
      }
    ]
    

    Below is the page that is displayed.

     SmartApp image setting

    Video Setting

    "settings": [
      {
        "id": "myVideoSetting",
        "name": "Play the video",
        "description": "Play the video",
        "type": "VIDEO",
        "video": "https://smartthings.developer.samsung.com/docs/how-to/img/video-sample.mp4"
      }
    ]
    

    Below is the page that is displayed.

     SmartApp video setting

    Time Setting

    "settings": [
      {
        "id": "myTimeSetting",
        "name": "Choose a time",
        "description": "Tap to set",
        "type": "TIME"
      }
    ]
    

    Below is the page that is displayed.

    SmartApp time setting


    Paragraph Setting

    "settings": [
      {
        "id": "myParagraphSetting",
        "name": "Some information title",
        "description": "Some description",
        "type": "PARAGRAPH",
        "defaultValue": "This is the information to display."
      }
    ]
    

    Below is the page that is displayed.

     SmartApp paragraph setting


    Email Setting

    "settings": [
      {
        "id": "myEmailSetting",
        "name": "Enter an email address",
        "description": "Tap to set",
        "type": "EMAIL"
      }
    ]
    

    Below is the page that is displayed.

    SmartApp email setting


    Decimal Setting

     "settings": [
      {
        "id": "myDecimalSetting",
        "name": "Enter a decimal value",
        "description": "Tap to set",
        "type": "DECIMAL"
      }
    ]
    

    Below is the page that is displayed.

    SmartApp decimal setting


    Number Setting

    "settings": [
      {
        "id": "myNumberSetting",
        "name": "Enter a number",
        "description": "Tap to set",
        "type": "NUMBER"
      }
    ]
    

    Below is the page that is displayed.

     SmartApp number setting


    Phone Setting

    "settings": [
      {
        "id": "myPhoneSetting",
        "name": "Enter a phone number",
        "description": "Tap to set",
        "type": "PHONE"
      }
    ]
    

    Below is the page that is displayed.

    SmartApp phone setting


    OAuth Settings

    "settings": [
      {
        "id": "myOauthSetting",
        "name": "Authenticate with the third party service",
        "description": "Tap to set",
        "type": "OAUTH",
        " urlTemplate : "https://accounts.artik.cloud/authorize?
    prompt=login&client_id=2134rwer34&response_type=code
    &redirect_uri=https%3A%2F%2Fapi.smartthings.com
    %2Foauth%2Fcallback", "
      }
    ]
    

    Below is the page that is displayed.

    SmartApp OAuth setting