Developers

Let’s take a closer look at how Riiiver works. The diagram below shows how the following iiidea – when you press the watch button, the current temperature is displayed on the clock face – works.

The iiidea shown above executes the following: ‘Watch button pressed > Retrieve current temperature > Move long hand’ In this example, the below components are included.

iiidea – A small app that consists of three Pieces. End-users can create iiidea using the Riiiver App (iPhone/Android).

Piece – The smallest individual components that, when combined, form an iiidea. There are three types of Pieces: ‘Trigger Pieces,’ ‘Service Pieces,’ and ‘Action Pieces.’ The combination of these pieces form the function shown above:

• Trigger Piece: Press the watch button.
• Service Piece: The current weather is retrieved from a web-based service.
• Action Piece: Weather is displayed with the watch’s hands.

Since iiidea is always operated in the order of ‘Trigger > Service > Action,’ each Piece includes connecting information with the preceding and succeeding Pieces.

PieceJSON – Piece Specification

PieceCore – The logic part of the Piece, which decides and completes the behavior of the Piece. The behavior of the Piece is then implemented on a mobile app.

Riiiver SDK – The Riiiver SDK contains the function to execute an iiidea sequentially in the order of ‘T > S > A’ (Trigger > Service > Action). Also, the Riiiver SDK is a framework, and it has some libraries to control/manage the Riiiver functions (when running iiidea on iOS/Android).

Lambda (AWS) – Environment prepared by Riiiver that can be used as a REST client (you don’t need to contract with Amazon yourself – Riiiver has prepared this for you). Using Lambda is optional, and you might not need this environment when using the Riiiver SDK for your function.

PieceJSON

When you create a Piece, you must define the specifications it will receive from the preceding Piece, and what it will send to the next Piece in sequence. This information is referred to as PieceJSON.

In the PieceJSON, the following information is detailed to explain to the end-users what this Piece can do:

• Piece name – In the above image, this is ‘Time arrival.’
• Piece description
• Piece category – The category name will be displayed in the app when users created iiidea containing the Piece (i.e. Weather & Nature, Communication, Sports & Entertainment).

The following terms are also related to Piece functionality:

• Input type – The type of information that this Piece can receive from the previous one.
• Output type – Data that a piece sends to the next Piece in sequence.
• Preferences – Configurable items that can be set when the user executes iiidea containing the Piece.
• Who provides the logic? – In other words, who is the source of the data in your Piece that you need to “call” in order to retrieve the information?

A sample PieceJSON for the above example is provided here.

{
  "title": {
    "en": "Current Temperature (celsius)",
    "ja": "現在の気温 (摂氏)"
  },
  "version": "1.0.0",
  "sdkVersion": "1.0.0",
  "deviceId": "none",
  "vendorId": "none",
  "description": {
    "en": "~~What is this Piece?~~\nGet the current temperature in degrees Celsius (°C).\n\n~~How do I use it?~~\nInclude this Piece in an iiidea to output a simple number representing the current temperature in °C.\nYou can choose in the iiidea settings for where to get information.\n\n~~Notes~~\nThe output value will be -50 if this Piece cannot get information due to network or a separate error.\n\nAbout Trademarks ( https://riiiver.com/en/trademark/ )",
    "ja": "【どんなPiece？】\n現在の気温を摂氏で次のPieceに渡します。\n\n【どうやって使うの？】\n「地域」のドラムロールから、気温を知りたい場所を選択してください。\n\n【ご注意！】\n気温をうまく取得できなかった場合は値が -50 となります。\n\n商標について ( https://riiiver.com/trademark/ )"
  },
  "blockType": "service",
  "executor": "RBCCommonWebServiceExecutor",
  "serviceProxy" : {
    "service": "pieceCore_sample"
  },
  "pieceCapability": "notUse",
  "preferences": {
    "type": "object",
    "properties": {
      "cityName": {
        "type": "string",
        "enum": [
          "Sapporo-shi",
          "Tokyo",
          "Osaka",
          "Fukuoka-ken",
          "Okinawa-ken"
        ],
        "default": "Tokyo",
        "x-input-type": "drumroll",
        "x-title": {
          "ja": "地域",
          "en": "Area setting"
        },
        "x-description": {
          "en": "set the area from which to get the temperature.",
          "ja": "気温を取得する地域を指定します。"
        },
        "x-enum-titles": {
          "Sapporo-shi": {
            "ja": "札幌市",
            "en": "Sapporo"
          },
          "Tokyo": {
            "ja": "東京都",
            "en": "Tokyo"
          },
          "Osaka": {
            "ja": "大阪府",
            "en": "Osaka"
          },
          "Fukuoka-ken": {
            "ja": "福岡県",
            "en": "Fukuoka"
          },
          "Okinawa-ken": {
            "ja": "沖縄県",
            "en": "Okinawa"
          }
        }
      }
    }
  },
  "output": {
    "type": "object",
    "properties": {
      "celsiusTemperature": {
        "type": "number",
        "minimum": -50,
        "maximum":  50
      }
    }
  },
  "osType":"none",
  "categoryIds": ["cat_0007"]
}

The following is a description of the keys included in the above JSON extract (Please refer to the PieceJSON Keys page for the definition of each JSON Key).

title

Provides the name of the piece. In the example above, the title has been provided in both English and Japanese. When users search for Pieces in the Riiiver app, the title is the first thing they’ll see, so please consider using an easy-to-understand and descriptive name.

version

Attaches the Piece version number (i.e. v.1.0.0 at the beginning). Version numbers are dictated by whoever creates/updates them. If you or someone else updates a Piece, please remember to update the version number when doing so.

sdkVersion

Specifies the SDK version required for running a Piece (There are no limitations on whether the SDK can be run or not, so it is OK to use at 1.0.0).

description

The description of the Piece. Like the title, this is what users will see when creating iiidea. Things to consider or explain when creating the description can include: what a user could do with the Piece, what kind of value they might get from using the Piece, and whether there any restrictions to using the Piece (such as using an API that only functions correctly in a certain timezone). There are some rules on making a description to be referred.

blockType

Provides the Piece type, i.e. Trigger Piece, Service Piece, or Action Piece.

executor

The name of the PieceCore class that operates the Piece (in the case of a ServicePiece that connects to a web service, specify the class RBCCommonWebServiceExecutor to use Lambda).

serviceProxy

For Service Pieces, when connecting to a specific web service, please specify the function(s) that need to be called via the Lambda environment.

preferences

The settings that a user can change when they use iiidea, including this Piece. In the above example, the drumroll is set to display “For which area would you like to know the current temperature?” for the user. Click here for a list of settings that the user can set.

output

The kind of output data the Piece contains. In this case, the weather temperature numbers are the output. Click here to see what else can be used.

osType

If the operation of a Piece is dependent on a certain smartphone OS, it should be written here. If a Piece can operate without requiring either iOS or Android, put ‘none’ in this field.

categoryIds

Assign a category to which the Piece belongs. Your Piece will be shown in the selected category when a user builds an iiidea using the Riiiver app.

Run-time behavior and PieceCore

Pieces are actually run by the RiiiverSDK inside the user’s smartphone. When the user selects an iiidea and activates the Trigger Piece, the process shown in the following diagram begins.

This figure shows the timing of when the Service Piece begins processing when the iiidea is being executed.

When the Riiiver SDK executes an S Piece, it calls the class (instance) in your app code defined by the "executor" key of the PieceJSON. If you implement any behaviors in this class, the Riiiver SDK will execute your class with the input parameters defined in the PieceJSON and the preference value specified by the user (when applicable). After the processing of your class finishes, the value returned by the class is forwarded to the next Piece as is.

The code part (your class) that you write is called PieceCore in Riiiver.

Implementing PieceCore

PieceCore operates locally inside the smartphone. In Android environments, PieceCore is packaged with Java or Kotrin, whereas in iOS it is packaged with Swift, or must be coded in a native environment. However, as most Pieces require external data sets on the Web, running on top of the native environment, Riiiver offers the following two methods for creating Pieces.

1. Completing a Piece using the Riiiver SDK. The PieceCore, the logic part of the Piece, is implemented on a mobile app.
2. Completing a piece using the AWS Lambda environment provided by Riiiver (there’s no need to develop the PieceCore when choosing this option).

To create Pieces, you must first register for a Riiiver Developer account.