Developers

preferencesとは？

Preferenceは皆さまが作成したPieceがiiideaの一部として実行される前に、エンドユーザーにセットしてほしい設定項目を定義します。ユーザーは各自のiPhone/Android端末にダウンロードしたiiideaの詳細画面から、設定情報を入力することになります。

ここでは各UIについての定義方法を説明します。

位置情報を利用する

Pieceを作るときにユーザーの位置を使用したい場合があります。この機能ではユーザーが位置情報またはmapで指定した座標を取得する事ができます。

preferences画面の例

ユーザーはPreference内のcheckboxで現在の位置情報を利用するか、mapで座標を指定するか選ぶ事ができます。

位置情報利用時

map利用時

Piece JSONへの記載

位置情報を利用するために、PieceJSONに"permissionList"と、"serviceProxy"に"parameters"と"x-location-default"を追加します。追加すると上記のUIが表示されるため"preferences"への記載はいりません。

"permissionList":{
  "ios":["location"],
  "android":["location"]
},
"serviceProxy":{
  "service":"citizenSample",
  "parameters":["location_accurate"],
  "x-location-default": [   ///　マップ利用時のデフォルト座標を設定します。 
    35.681247,
    139.767019
  ]
},

・・・

"preferences": {
  "type": "object",
  "properties": {
    ///　ここで位置情報に関する記載はしません。
    ///　他にpreferenceのkeyが必要ない場合は"preferences"の定義ごと必要ありません。
  }
},

permissionList

"permissionList"はどのOSタイプの位置情報利用の許可が必要かを記載します。
"permissionList"には"ios"、"android"のJSON KeyをPiece JSON内の"osType"に応じて記入してください。JSON Keyの値は、いずれも["location"]です。

○：必須、×：不要

parameters

"parameters"は位置情報の精度を記載します。
parametersには表のいずれかの項目を記入してください。より良い精度の位置情報を使用すると、位置情報の取得時間が長くなります。

x-location-default

"x-location-default"はmapを利用する場合のデフォルト値を指定します。

設定項目

指定区分：○・・・必須、△・・・任意、×・・・不要

ProxyCoreで現在位置を取得

PieceJSONにparametersを追加するとProxyCore(.jsファイル内)で以下のように位置情報（緯度・経度）を取得できます。

※いずれの精度を指定していても以下のコードで取得できます。

exports.handler = async event => {
  const latitude = event.properties.parameters.location.latitude;
  const longitude = event.properties.parameters.location.longitude;
  // 位置情報を使った処理を実行
}

drumroll

いくつか決められた項目から1つを選択できるUIを表示します。
有効なtypeはstringとnumberです。UIの性質上、選択肢が多すぎると入力が煩雑になってしまうので、多くても100個前後までにとどめることを推奨します。

drumroll(string)

preferences画面の例

drumroll close時

drumroll open時

設定項目　

指定区分：○・・・必須、△・・・任意、×・・・不要

PieceJSONの例

"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の例

// drumrollで入力された値が入る("Saitama" or "Chiba" or "Tokyo" or "Kanagawa") 
let prefecture = event.properties.preferences.prefecture;

drumroll(number)

numberの場合はdrumroll(string)のようにenumで設定する方法と、最小(minimum)・最大(maximum)・数値の間隔(multipleOf)を設定する方法の２つがあります。要素数が少ない場合や、値に規則性がない場合はenum、要素数が多い場合は最小・最大・数値の間隔を設定する方法がおすすめです。 ２つの設定項目を示したあと、最小・最大・数値の間隔を指定する方法の例を示します。

preferences画面の例

drumroll close時

drumroll open時 

設定項目　

enumで設定する方法

指定区分：○・・・必須、△・・・任意、×・・・不要

最小・最大・数値の間隔を設定する方法

指定区分：○・・・必須、△・・・任意、×・・・不要

PieceJSONの例

下記は、10（minimum）から200（maximum）の範囲を1の間隔（multipleOf）で入力できるdrumrollの定義例です。

"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の例

// drumrollで入力された値が入る(10~200)
let height = event.properties.preferences.height;

text

1行の文字列を入力できるUIを表示します。
有効なtypeはstringです。ユーザーに柔軟に入力を求めることが可能です。
maximumを設定することで、入力を制限することができます。

preferences画面の例

設定項目　

指定区分：○・・・必須、△・・・任意、×・・・不要

PieceJSONの例

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

ProxyCoreの例

//textで入力された値が入る(文字列)
let name = event.properties.preferences.name;

textarea

複数行の文字列を入力できるUIを表示します。
有効なtypeはstringです。ユーザーに柔軟に入力を求めることが可能です。
maximumを設定することで、入力を制限することができます。

preferences画面の例

設定項目　

指定区分：○・・・必須、△・・・任意、×・・・不要

PieceJSONの例

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

ProxyCoreの例

//textareaで入力された値が入る(文字列)
let message = event.properties.preferences.message;

slider

指定した範囲の数値を入力できるUIを表示します。
有効なtypeはnumberです。指定した値が全体の範囲のどの位置にあるのか、視覚的にわかりやすくなります。

preferences画面の例

設定項目　

指定区分：○・・・必須、△・・・任意、×・・・不要

PieceJSONの例

下記は、0（minimum）から100（maximum）の範囲を10の間隔（multipleOf）で入力できるsliderの定義例です。

"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の例

//sliderで入力された値が入る(0~100)
let brightness = event.properties.preferences.brightness;

calendar

カレンダーから年月日を入力できるUIを表示します。
有効なtypeはstringです。年月日の範囲で入力してほしい場合に使用します。

preferences画面の例

設定項目　

指定区分：○・・・必須、△・・・任意、×・・・不要

PieceJSONの例

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

ProxyCoreの例

//calendarで入力された値が入る(yyyy-mm-dd)
let reservation = event.properties.preferences.reservation;

radio

いくつか決められた項目から一つを選択できるUIを表示します。
有効なtypeはstringです。drumrollとは違い、選択項目がすべて画面上に表示されるため、2～5項目前後の選択肢であれば、こちらを使用することを推奨します。

preferences画面の例

設定項目　

指定区分：○・・・必須、△・・・任意、×・・・不要

PieceJSONの例

"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の例

// radioで入力された値が入る("age18"or"age29"or"age39"or"age49"or"age50")
let age = event.properties.preferences.age;

map

地図上から位置を選択できるUIとなります。
有効なtypeはarrayです。場所を指定してほしい場合に使用します。

preferences画面の例

設定項目　

指定区分：○・・・必須、△・・・任意、×・・・不要

PieceJSONの例

"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の例

//mapで入力された値が入る([latitude,longitude])
let destination = event.properties.preferences.destination;
let latitude = destination[0];
let longitude = destination[1];

switch

2択用のUIを表示します。
有効なtypeはbooleanです。シンプルに2択で表現できる情報であればこちらを使用することを推奨します。

preferences画面の例

設定項目　

指定区分：○・・・必須、△・・・任意、×・・・不要

PieceJSONの例

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

ProxyCoreの例

//switchで入力された値が入る(true or false)
let func = event.properties.preferences.function;

time

時刻入力用のUIを表示します。
有効なtypeはarrayです。時刻の範囲で入力してほしい場合に使用します。

preferences画面の例

設定項目　

指定区分：○・・・必須、△・・・任意、×・・・不要

PieceJSONの例

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

ProxyCoreの例

//timeで入力された値が入る([hour,minute])
let wakeUp = event.properties.preferences.wakeUp;
let hour = wakeUp[0];
let minute = wakeUp[1];

Preferencesの表示順

Preferences内のpropertiesの表示順を指定することができます。
表示順を指定しない場合には、記載した順番にならないことがあります。

指定方法

"x-field-order"にpropertiesのKeyを表示の並び順に記載して指定します。下記例では、"travelmode"、"select"、"dest1"、"dest2"のKeyの順に表示されるよう記述しています。

"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"
      }
    }
  }
},