Register your Piece

Contents

When you finish debugging your Pieces, it’s time to share them with the world. You can upload Pieces using the developer portal site.


Preparing items before uploading

Your Piece probably falls into 1 of the following categories:

If you made an S/A piece using the Riiiver-ready Lambda:

The folder you created must be arranged as follows:

SampleCode
├── .vscode
├── kicker_on_lambda.js
└── YourCode
    ├── JSON
    │   └── pieceJson_Sample.json
    ├── ProxyCore
    │   ├── pieceCore_Sample.js      ☆
    │   ├── pieceCore_divieded_A.js  ☆
    │   ├── pieceCore_divieded_B.js  ☆
    │   ├── node_modules             ☆ (including all files under this folder)
    │     .... tons of node module files ....
    │   │   
    │   └── package-lock.json
    └── event.json

You have to compress (aka zip) your source files before uploading them. It is essential that you zip the correct files, which are marked above with "☆." You do not need to zip the PieceJSON itself; however, do not forget to also zip the node_modules folder stored therein. *IMPORTANT:* Do not include the "ProxyCore" folder as a whole when zipping. You must select and zip only the files/folders marked as "☆." If the hierarchical relationship you establish between these target files/folders is wrong, your Piece will not work well with Lambda.

Now you are ready to upload! Go to Upload your piece via PieceBuilder for more detail on how exactly to upload.

If you natively coded a PieceCore that utilizes the Riiiver SDK

You do not need to zip any files before uploading your Piece.


Upload your Piece via PieceBuilder

"PieceBuilder" is the system on our developer portal site via which you actually upload your Piece. First, log in to the developer site from here and click on "Piece List."

This will take you to the following page.

This is the page where you can manage your Pieces, and, if this is your first Piece, it will look pretty blank to start. Click the "Register a Piece JSON" button to upload your piece.

Again you'll be looking at a fairly empty page, but if you now have the below options, you're in the right place. Click the "Upload" button:

Now select your PieceJSON file. We will use the following PieceJSON file for our demo here:

{
    "title": {
        "en": "Current Temperature (celsius)",
        "ja": "現在の気温 (摂氏)"
    },
    "version": "1.0.0",
    "sdkVersion": "1.0.0",
    "deviceId": "none",
    "vendorId": "none",
    "description": {
        "en": "Current temperature in the setting area",
        "ja": "指定した地域の現在の気温を取得します。うまく取得できなかった場合は値が -1 となります。"
    },
    "blockType": "service",
    "executor": "RBCCommonWebServiceExecutor",
    "serviceProxy": {
        "service": "pieceCore_Sample"
    },
    "preferences": {
        "type": "object",
        "properties": {
            "cityName": {
                "type": "string",
                "format" : "text",
                "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",
                "x-title" : {
                "en" : "Output the selected city's temperature in celsius.",
                "ja" : "指定した都市の温度を摂氏で出力します。"
                },
                "minimum" : -50,
                "maximum" : 50 
            }
        }
    },
    "osType": "none",
    "categoryIds": ["cat_0007"]
}

If you are using the sample project, the PieceJSON file should be located at SampleCode/YoueCode/JSON. Upon uploading a correctly formatted PieceJSON file, you should see a screen that looks like this:

This screen is the PieceBuilder, which analyzes your PieceJSON file and displays the result. If you see any errors, your PieceJSON file likely has some issues. Some required information may be lacking, or the JSON format may be incomplete/broken. Please refer to the documentation on Piece specifications to identify your error and and update your PieceJSON accordingly before attempting to upload again.

There are four additional orange buttons at the bottom of the PieceBuilder screen here where you can provide additional material, described below. Note that only the icon file is required.

Choose ServiceProxyCore (Zip file)

If you made an S/A piece using the Riiiver-ready Lambda, here is where you can upload the zipped file you made in the Preparing items before uploading section. If you made a native code Piece that uses the Riiiver SDK, this zip file is not needed.

To upload your zip file, click the orange button. The Riiiver system will load and deploy your zip file to execute AWS Lambda functions on the Riiiver server.

Choose an icon file (Required)

Set an icon to represent your Piece. There are two methods to selecting an icon:

  1. Prepare the icon file yourself (in png format) and upload it.
  2. Make a simple icon within PieceBuilder using Font Awesome.
If you upload your own icon:

Please follow these rules:

  • PNG format file
  • The size of the file must be larger than 512 x 512 px.

After clicking to "Choose an icon file," press the "Upload" button (circled in blue below) to select your target file.

Create icon using PieceBuilder built-in features

You can also make a modest icon utilzing our built-in features powered by Font Awesome within the PieceBuilder environment. Select a simple shape and color to represent your Piece:

1. In the "Select icon" section (marked in yellow below), enter a keyword that befits your Piece to search for an image you like.

In this example, we're going to type "temp" as a keyword to see if we can find a suitable image for our sample PieceJSON - Current Temperature. Here are our results:

2. You can see more results by clicking the arrow buttons circled in yellow on the sides. Click an icon to preview it and finesse the color. When finished adjusting your icon, click OK.

i. Confirm the name of the icon file upon upload.

Choose an illustration file

An illustration file is a picture that appears in the Piece description in the Riiiver App to help the user better understand how the function you've designed works. For example, the "Calendar" Piece created by Citizen contains the following illustration file. (Note that this file, which appears within the description, is different from the main Piece icon.)

The "watch illustration" with the pink arrow below is called an illustration file. You can only specify 1 illustration file per Piece.

Your illustration file must follow the following format rules:

  • PNG format only
  • Between 512x512px ~ 1200x1200px size

When creating an iiidea via the Riiiver App, the user will read your Piece description when assembling their iiidea. If you include a picture that makes it easier for the user to understand your Piece at a glance, the potential use of your Piece increases exponentially. Definitely consider the impact of combining an excellent text explanation with a clear illustration. Most users will see your Piece description on their smartphone, so please also consider this environment when designing your illustration file.

Set OAuth file

This file is optional, but if you need an OAuth authentication function for your Piece, please use this option. (The detailed explanation page : Creating Pieces that work with external services requiring OAuth authorization)


Upload Complete

When you have finished specifying/uploading all the necessary files, click the "Confirm" button at the bottom right of the PieceBuilder screen. If our system reads all your settings as correct (pieceJSON, icon file specification, etc.), you should arrive at the following screen.

If you've encountered another error, an error code should be displayed. Please check your JSON file and try again.

Once successfully uploaded, the Riiiver team will review your Piece. As shown in the following screen, if your submission is noted as a "Success," you should see on the "Piece list" screen that your submission is now waiting review. Because the technical component of some Pieces may be complicated, please allow us a few business days to review your submission. We will communicate via the email address registered to the submitting profile.

And with that, you've uploaded your Piece! Definitely be on the lookout for any communication from the Riiiver review team regarding its review, but, once approved, you'll get an approval email from us and immediately be available to Riiiver users!