Developers

About preferences

Using preferences, you can allow end users to configure certain iiidea settings to meet their particular wants. Each piece can have multiple preference items, and these items will display to end users via a preference setting UI you choose. This function is possible in both the Apple and Android environments.

In this document, we will look at the various preference interfaces possible using the Riiiver SDK on iPhone/Android.

Drumroll

The ‘drumroll’ UI allows the user to scroll through a list of selectable items. Acceptable inputs are string and number.

Note: The more choices, the more complicated the drumroll selection becomes for the user, so it is recommended to limit options to 100 or fewer.

Drumroll (string)

Preferences screen examples

Drumroll closed

Drumroll open

Preference Settings

Symbol legend ：○・・・Yes、△・・・Optional、×・・・No

PieceJSON example

"prefecture": {
  "type": "string",
  "x-description": {
    "ja": "好きな地域を入力してください。",
    "en": "Enter your favorite prefecture"
  },
  "enum": [
    "Saitama",
    "Chiba",
    "Tokyo",
    "Kanagawa"
  ],
  "x-input-type": "drumroll",
  "default": "Tokyo",
  "x-title": {
    "ja": "地域",
    "en": "Light setting"
  },
  "x-enum-titles": {
    "Saitama": {
      "ja": "埼玉県",
      "en": "Saitama"
    },
    "Chiba": {
      "ja": "千葉県",
      "en": "Chiba"
    },
    "Tokyo": {
      "ja": "東京都",
      "en": "Tokyo"
    },
    "Kanagawa": {
      "ja": "神奈川県",
      "en": "Kanagawa"
    }
  }
},

ProxyCore example

// The value set by the end user via the drumroll functionality ("Saitama" or "Chiba" or "Tokyo" or "Kanagawa") 
let prefecture = event.properties.preferences.prefecture;

Drumroll (number)

When using a number preference, there are two general approaches: Go at it from the drumroll (string) angle with limited "enum" choices, or from an interval “multipleOf” angle focused on having the user select minimum and maximum settings. When the numerical output is limited or irregular, the drumroll “enum” approach is recommended. However, if the output possibilities are extensive, consider setting maximum, minimum, and interval values. Check the below for examples of each.

Preferences screen examples

Drumroll closed

Drumroll open

Preference Settings

Setting via Enum

Symbol legend：○・・・Yes、△・・・Optional、×・・・No

Setting via Minimum・Maximum・Interval

Symbol legend：○・・・Yes、△・・・Optional、×・・・No

PIeceJSON example

Below is an example of a drumroll, which has a range minimum of 10 and a maximum of 200, with an interval of 1 (multipleOf).

"height":{
  "type":"number",
  "x-description":{
    "ja":"あなたの身長を入力してください。",
    "en":"Please enter your height."
  },
  "maximum":200,
  "minimum":10,
  "multipleOf":1,
  "x-input-type":"drumroll",
  "default":150,
  "x-title":{
    "ja":"身長",
    "en":"height"
  }
},

ProxyCore Example

// The value set by the end user via the drumroll functionality (10~200)
let height = event.properties.preferences.height;

Text

The end user enters a line of text to ‘feed’ the iiidea. You can use this UI to request a small amount of information, such as an email address. In Riiiver, you can use only the string type for the text preference.

Acceptable input: string

Preferences screen example

Preference Settings

Symbol legend：○・・・Yes、△・・・Optional、×・・・No

PieceJSON example

"name":{
  "type":"string",
  "x-description":{
    "ja":"名前を入力してください。",
    "en":"Please enter your name."
  },
  "x-input-type":"text",
  "default":"test",
  "x-title":{
    "ja":"名前",
    "en":"name"
  }
},

ProxyCore example

// The value set by the end user via text entry will be included here as “name”
let name = event.properties.preferences.name;

Textarea

The end user can ‘feed’ the iiidea with multiple lines of text information. Using this preference, end users can type much longer.

Acceptable input: string

Preferences screen example

Preference Settings

Symbol legend：○・・・Yes、△・・・Optional、×・・・No

PieceJSON example

"message":{
  "type":"string",
  "x-description":{
    "ja":"メッセージを入力してください。",
    "en":"Please enter your message"    
  },
  "x-input-type":"textarea",
  "default":"test",
  "x-title":{
    "ja":"メッセージ",
    "en":"message"
  }
},

ProxyCore example

// The value set by the end user will be included here as “message”
let message = event.properties.preferences.message;

Slider

A slider lets the user slide their finger to move between a minimum and maximum value, such as when you change the screen brightness level on your phone. Allow users to select a number within your decided range in a way that is easy for them to visually identify where their specified value aligns within the entire range.

Acceptable input: number

Preferences screen example

Preference Settings　

Symbol legend：○・・・Yes、△・・・Optional、×・・・No

PieceJSON example

A slider that has a minimum of 0 and a maximum of 100 values, with an interval (multipleOf) of 10.

"brightness":{
  "type":"number",
  "x-description":{
    "ja":"ライトの明るさを指定してください。",
    "en":"Brightness setting"
  },
  "maximum":100,
  "minmum":0,
  "multiplierOf":10,
  "x-input-type":"slider",
  "default":30,
  "x-title":{
    "ja":"明るさ",
    "en":"brightness"
  }
},

ProxyCore example

// The value set by the end user will be included here. (0 - 100)
let brightness = event.properties.preferences.brightness;

Calendar

Use a calendar interface to allow the end user to select a specific date. The data format used by Riiiver for dates is ‘yyyy-mm-dd’.

Acceptable input: string

Preferences screen example

Preference Settings　

Symbol legend：○・・・Yes、△・・・Optional、×・・・No

PieceJSON example

"reservation":{
  "type":"string",
  "x-description":{
    "ja":"予約日を指定してください。",
    "en":"Please enter a reservation date."
  },
  "format":"date",
  "default":"2019-5-13",
  "x-input-type":"calendar",
  "x-title":{
    "ja":"予約日",
    "en":"reservation"
  }
},

ProxyCore example

// The value the set by the end user will be included here as (yyyy-mm-dd)
let reservation = event.properties.preferences.reservation;

Radio

Allow end users to select a single item from a list of items available via radio buttons. Unlike drumroll, all of the options are available on-screen at once, so it is recommended that you only provide 2-5 options at a time.

Acceptable input: string

Preferences screen example

Preference Settings　

Symbol legend：○・・・Yes、△・・・Optional、×・・・No

PieceJSON example

"age":{
  "type":"string",
  "x-description":{
    "ja":"年齢を選んでください。",
    "en":"Please enter your age."
  },
  "enum":["age18","age29","age39","age49","age50"],
  "default":"age29",
  "x-input-type":"radio",
  "x-title":{
    "ja":"年齢",
    "en":"age"
  },
  "x-enum-titles":{
    "age18":{
      "ja":"18歳未満",
      "en":"~18"
    },
    "age29":{
      "ja":"18~29歳",
      "en":"18~29"
    },
    "age39":{
      "ja":"30~39歳",
      "en":"30~39"
    },
    "age49":{
      "ja":"40~49歳",
      "en":"40~49"
    },
    "age50":{
      "ja":"50歳以上",
      "en":"50~"
    }
  }
},

ProxyCore example

// The value selected by the end user via a text UI will be set here 
// ("age18"or"age29"or"age39"or"age49"or"age50")
let age = event.properties.preferences.age;

Map

Allow users to select and set a location using Google Maps.

Acceptable input: array

Preferences screen example

Preference Settings　

Symbol legend：○・・・Yes、△・・・Optional、×・・・No

PieceJSON example

"destination":{
  "type":"array",
  "x-description":{
    "ja":"行き先を指定してください。",
    "en":"Please enter your destination."
  },
  "default":[
    35.681247,139.767019
  ],
  "x-input-type":"map",
  "x-title":{
    "ja":"行き先",
    "en":"destination"
  }
},

ProxyCore example

// The value selected by the end user will be set here. [latitude,longitude]
let destination = event.properties.preferences.destination;
let latitude = destination[0];
let longitude = destination[1];

Switch

A switch has the user interact with a visual toggle to select between two mutually exclusive states — on or off.

Acceptable input: boolean

Preferences screen example

Preference Settings　

Symbol legend：○・・・Yes、△・・・Optional、×・・・No

PieceJSON example

"function":{
  "type":"boolean",
  "x-description":{
    "ja":"機能を有効にします。", 
    "en":"Enable the function."
  },
  "x-input-type":"switch",
  "default":true,
  "x-title":{
    "ja":"機能を有効",
    "en":"Function enabled."
  }
},

ProxyCore example

// The value selected by the end user will be set here. (true or false)
let func = event.properties.preferences.function;

Time

Use the ‘Time’ preference to give users an efficient interface for selecting a specific time.

Acceptable input: array

PieceJSON example

Preference Settings

Symbol legend：○・・・Yes、△・・・Optional、×・・・No

PieceJSON example

"wakeUp":{
  "type":"array",
  "x-description": {
    "ja": "今日起きた時間を入力してください。",
    "en": "Enter the time before you wake up"
  },
  "x-input-type":"time",
  "default":[10,15],
  "x-title":{
    "ja":"起床時間",
    "en":"Wake-up time"
  }
},

ProxyCore example

// The value set by the end user via a text UI will be set here [hour,minute]
let wakeUp = event.properties.preferences.wakeUp;
let hour = wakeUp[0];
let minute = wakeUp[1];

Preference UI Display Order

When using multiple-preference UIs in your Riiiver Piece, you can set the order in which they appear to the user. If you do not establish a sorting order, the order in which they are displayed may be random.

How to configure your desired order

You can set the display order using the "x-field-order" keyword. See the following example in which we use this keyword to set the display order as:

1. "select"
2. "dest1"
3. "dest2"
4. "travelmode"

The user will see these selections in this order, even though this arrangement is different from how it appears in the code.

"preferences":{
  "type":"object",
  "x-field-order":["select","dest1","dest2","travelmode"],
  "properties":{
    "travelmode":{
      "type":"string",
      "x-description":{
        "ja":"交通手段を選択してください。",
        "en":"Select your travel mode"
      },
      "enum":[
        "none",
        "drive",
        "walk",
        "transit"
      ],
      "x-input-type":"drumroll",
      "default":"none",
      "x-title":{
        "ja":"(オプション)交通手段",
        "en":"(option) Travel mode"
      }
    },
    "select":{
      "type":"string",
      "x-description":{
        "ja":"どちらの目的地を使用しますか？",
        "en":"Please select Map1 or Map2 as Destination"
      },
      "enum":["map1","map2"],
      "default":"map1",
      "x-input-type":"radio",
      "x-title":{
        "ja":"目的地を選択",
        "en":"Select to set destination"
      }
    },
    "dest1":{
      "type":"array",
      "x-description":{
        "ja":"目的地を指定してください。",
        "en":"Please enter your destination."
      },
      "x-input-type":"map",
      "x-title":{
        "ja":"Map1",
        "en":"Map1"
      }
    },
    "dest2":{
      "type":"array",
      "x-description":{
        "ja":"目的地を指定してください。",
        "en":"Please enter your destination."
      },
      "x-input-type":"map",
      "x-title":{
        "ja":"Map2",
        "en":"Map2"
      }
    }
  }
},