API Reference

Advanced Command Parameters

Overview

Sub categories for commands is an advanced feature that requires enabling a special feature for the OEM. Please contact support for details on how to enable it.

Sub Category Parameters

Overview

This feature allows to split very large drop-down choice menus into two parters, where the End User can first select from a shorter drop-down which will generate a related drop-down with filtered values.

For example, when selecting a song the End User can be presented with a drop-down of genre and after selecting one, presented with a follow up drop-down with songs only from that genre.

The information can be specified per-device, so each device can support different genres and music lists.

Setup

Two main steps are required for this feature to work:

  1. Setup a command with two parameters.
  2. Make sure the device's details field contains the allowed values.

Setup a command

  1. Create a new command (e.g. "select music")

  2. Add the primary parameter:

    1. Required - True

    2. Hidden - False

    3. Field key - e.g. music_genre

    4. Label - e.g. Genre

    5. Field type - Dynamic list (single select)

    6. Path - e.g. details.music_choices

  3. Add the secondary parameter:

    1. Required - True

    2. Hidden - True

    3. Field key - e.g. song

    4. Label - e.g. Song

    5. Field type - string


Full command configuration:


Set device's details

Use the Update Device API to set the details to contain a key where the options are stored, in the following format:

{
  "field_where_options_are_saved": [
    { category_1_data },
    { category_2_data },
    { category_3_data },
		...    
  ]
}

{
  "label": "What user sees in primary drop-down",
  "children": data for secondary
}

{      
	"key": "Secondary parameter Field Key",
  "label": "Secondary parameter label",
   "options": array of string values for secondary drop-down
}

Sample data:

{
  "music_choices": [
    {
      "label": "Pop",
      "children": {
        "key": "song",
        "label": "Song",
        "options": [
          "Wannabe", "2 Become 1", "Spice Up Your Life"
        ]
      }
    },
    {
      "label": "Rock",
      "children": {
        "key": "song",
        "label": "Song",
        "options": [
          "Creep", "Alive", "No Rain"
        ]
      }
    }
  ]
}

Usage

On the End Customer side, when clicking a command the user will be presented with the option to select one of the Primary options and after selecting one a new drop-down will be auto-generated for the Secondary selection.

The enqueued command will have both send in the command's parameter field.

Will result in the following data of the command:

{
  "song": "No Rain",
  "genre": "Rock"
}