kintone プラグイン開発手順

目次

はじめに

kintone では、「プラグイン」を利用して、JavaScript カスタマイズと同等の機能拡張や他サービスとの連携を実現できます。
通常のカスタマイズではアプリに合わせて JavaScript ファイルを編集する必要がありますが、プラグインを使うと、プラグインの設定画面でそれぞれのアプリに合わせた設定ができます。

プラグインは、kintone をカスタマイズするための JavaScript や CSS ファイルをパッケージングしたものです。

この記事では、プラグインの作成手順と kintone へのインストール方法について説明します。

プラグイン作成の流れ

プラグイン作成の手順は、以下のとおりです。

  1. プラグイン作成に必要なファイル(JavaScript, CSS ファイルなど)を準備します。
  2. マニフェストファイル(manifest.json)を作成します。
  3. パッケージツール(plugin-packer)を利用して、プラグイン作成に必要なファイルをパッケージングします。
  4. 作成したプラグインファイルを kintone 環境にインストールします。

プラグイン作成に必要なファイルの準備

パッケージングするファイルを準備します。
パッケージングするファイルのディレクトリー構成およびファイル名は自由です。

以下は一例です。

アイコンファイル

プラグイン一覧、プラグイン設定画面で表示されるプラグインアイコン用のファイルです。

  • 必須ファイルです。
  • 利用可能なファイルタイプは、png/jpg/gif/bmp のいずれかです。
  • ファイルサイズの上限値は、20MB です。

PC 用 JavaScript ファイル

PC 画面用の JavaScript ファイルです。

  • モバイル専用のプラグインの場合、省略可能です。
  • 設定画面で設定した情報を使い、実装したい処理を記述します。
  • 設定画面用の JavaScript ファイルで プラグインの設定情報を保存する API を利用して設定した情報は、 プラグインの設定情報を取得する API を利用して取得します。
    このとき必要なプラグイン ID は、 kintone.$PLUGIN_ID という変数に出力されます。
    プラグイン ID は、プラグイン作成時に各プラグインへ一意に割り当てられる 32 桁の ID です。
    例:faabchdodajloackbgnipilddblmkejp
  • ファイルサイズの上限値は、20MB です。
プラグイン ID の参照例

1 アプリで複数のプラグインを利用する場合、kintone.$PLUGIN_ID は複数回代入されます。
そのため、以下のように即時実行関数でプラグイン ID を補足して利用してください。

1
2
3
((PLUGIN_ID) => {
  kintone.plugin.app.getConfig(PLUGIN_ID);
})(kintone.$PLUGIN_ID);

PC 用 CSS ファイル

PC 画面用の CSS ファイルです。

  • モバイル専用のプラグインの場合、省略可能です。
  • kintone のデザインに合わせたい場合は、 51-modern-default を利用してください。
  • ファイルサイズの上限値は、20MB です。

モバイル用 JavaScript ファイル

モバイル用の JavaScript ファイルです。

モバイル用 CSS ファイル

モバイル画面用の CSS ファイルです。

  • モバイルでプラグインを利用しない場合、省略可能です。
  • ファイルサイズの上限値は、20MB です。

設定画面用 JavaScript ファイル

設定画面用の JavaScript ファイルです。

設定画面用 CSS ファイル

設定画面用の CSS ファイルです。

  • 省略可能です。
  • kintone のデザインに合わせたい場合は、 51-modern-default を利用してください。
  • ファイルサイズの上限値は、20MB です。
  • プラグイン設定画面に対し適用される CSS ファイルです。

設定画面用 HTML ファイル

設定画面用の HTML ファイルです。

  • 省略可能です。
  • ファイルサイズの上限値は、64KB です。
  • 下図の赤枠部分を構成する HTML ファイルです。

マニフェストファイルの作成

マニフェストファイル(manifest.json)を作成します。
マニフェストファイルは、プラグイン作成に必要なファイル情報をまとめた設定ファイルです。
このファイルは、kintone プラグイン作成に必須です。

マニフェストファイルのフォーマット

マニフェストファイルは、JSON 形式のファイルです。
各パラメーターの詳細は以下のとおりです。

パラメーター名 必須 説明 制限 指定例
type 文字列 必須 プラグインの種類
「APP」を指定してください。
なし
"type": "APP"
manifest_version 数値 必須 プラグインのマニフェストバージョン
「1」を指定してください。
なし
"manifest_version": 1
version 数値
または
文字列
必須 プラグインのバージョン
数値を指定する場合は整数のみです。
文字列を指定する場合、「x」「x.y」「x.y.z」の形式のみです。
なし 数値の場合
"version": 1
文字列の場合
"version": "1.0"
"version": "1.0.0"
name オブジェクト 必須 ロケール をキーとする各言語のプラグイン名 なし
"name": {
"ja": "サンプルプラグイン",
"en": "sample plugin",
"zh": "插件的例子",
"es": "Complemento de ejemplo"
}
name.<locale> 文字列 必須 指定されたロケールのプラグイン名 1 文字以上 64 文字以下
name.en は必須です。
description オブジェクト 省略可 ロケール をキーとする各言語の説明文
プラグイン一覧での説明文として表示されます。
なし
"description": {
"ja": "これはサンプルプラグインです。",
"en": "This is sample plugin.",
"zh": "这是插件的例子",
"es": "Este es un complemento de ejemplo."
}
description.<locale> 文字列 必須 指定されたロケールの説明文 1 文字以上 200 文字以下
description がある場合、description.en は必須です。
icon 文字列 必須 プラグインのアイコンファイル
プラグイン一覧画面とプラグイン設定画面で表示されます。
プラグイン内のファイルのみ指定可能です。
"icon": "image/icon.png"
homepage_url オブジェクト 省略可 ロケール をキーとする Web サイト URL
プラグイン一覧のプラグイン名横にナビゲーションアイコンが追加されます。
アイコンをクリックすると、指定した Web サイトに遷移します。
なし
"homepage_url": {
"ja": "https://example.com/ja/",
"en": "https://example.com/en/",
"zh": "https://example.com/zh/",
"es": "https://example.com/es/"
}
homepage_url.<locale> 文字列 省略可 指定されたロケールの Web サイト URL なし
desktop オブジェクト 省略可 ファイルの種類 (js/css) をキーとする PC 用カスタマイズファイル なし
"desktop": {
"js": [
"js/customize.js",
"https://example.com/js/customize.js"
],
"css": [
"https://example.com/css/customize.css",
"css/customize.css"
]
}
desktop.js 配列(文字列) 省略可 PC 用 JavaScript ファイル
URL の配列
30 個まで
同一名のファイルがある場合、エラーになります。
desktop.css 配列(文字列) 省略可 PC 用 CSS ファイル
URL の配列
30 個まで
同一名のファイルがある場合、エラーになります。
mobile オブジェクト 省略可 ファイルの種類 (js) をキーとするモバイル用カスタマイズファイル なし
"mobile": {
"js": [
"js/mobile-customize.js",
"https://example.com/js/mobile-customize.js"
],
"css": [
"https://example.com/css/customize.css",
"css/customize.css"
]
}
mobile.js 配列(文字列) 省略可 モバイル用 JavaScript ファイル
URL の配列
30 個まで
同一名のファイルがある場合、エラーになります。
mobile.css 配列(文字列) 省略可 モバイル用 CSS ファイル
URL の配列
30 個まで
同一名のファイルがある場合、エラーになります。
config オブジェクト 省略可 ファイルの種類 (js/css/html) をキーとする設定画面用カスタマイズファイルと設定情報 なし
"config": {
"html": "html/config.html",
"js": [
"js/config.js",
"https://example.com/js/config.js"
],
"css": [
"https://example.com/css/config.css",
"css/config.css"
]
"required_params": ["Param1", "Param2"]
}
config.html 文字列 省略可 設定画面用 HTML ファイル プラグイン内のファイルのみ指定可能
config.js 配列(文字列) 省略可 設定画面用 JavaScript ファイル
URL の配列
30 個まで
同一名のファイルがある場合、エラーになります。
config.css 配列(文字列) 省略可 設定用 CSS ファイル
URL の配列
30 個まで
同一名のファイルがある場合、エラーになります。
config.required_params 配列(文字列) 省略可 設定画面で設定必須とするパラメーターの配列 ASCII で 1 文字以上 64 文字以下
指定できるロケール

ロケールには、次の言語コードを指定できます。

  • ja:日本語
  • en:英語
  • zh:中国語(簡体字)
  • es:スペイン語
マニフェストファイルの例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
  "manifest_version": 1,
  "version": 1,
  "type": "APP",
  "name": {
    "ja": "サンプルプラグイン",
    "en": "sample plugin",
    "zh": "插件的例子",
    "es": "Complemento de ejemplo"
  },
  "description": {
    "ja": "これはサンプルプラグインです。",
    "en": "This is sample plugin.",
    "zh": "这是插件的例子",
    "es": "Este es un complemento de ejemplo."
  },
  "icon": "image/icon.png",
  "homepage_url": {
    "ja": "https://example.com/ja/",
    "en": "https://example.com/en/",
    "zh": "https://example.com/zh/",
    "es": "https://example.com/es/"
  },
  "desktop": {
    "js": ["js/customize.js", "https://example.com/js/customize.js"],
    "css": ["https://example.com/css/customize.css", "css/customize.css"]
  },
  "mobile": {
    "js": [
      "js/mobile-customize.js",
      "https://example.com/js/mobile-customize.js"
    ],
    "css": ["https://example.com/css/customize.css", "css/customize.css"]
  },
  "config": {
    "html": "html/config.html",
    "js": ["https://example.com/js/config.js", "js/config.js"],
    "css": ["css/config.css", "https://example.com/css/config.css"],
    "required_params": ["Param1", "Param2"]
  }
}

プラグインに必要なファイルのパッケージング

「plugin-packer」を利用してプラグインに必要なファイルをパッケージングし、プラグインファイルを生成します。

plugin-packer とは

plugin-packer は、プラグイン作成で必要なファイルを zip ファイルにパッケージングする CLI ツールです。
plugin-packer の詳細は、 plugin-packer を参照してください。

このツールを利用するには、Node.js が必要です。
Node.js のインストーラーは、 Node.js 公式サイト (External link) より入手してください。
必要な Node.js のバージョンの確認方法は、 plugin-packer | 下準備 を参照してください。

インストール方法

以下のコマンドを実行し、plugin-packer をインストールします。

1
npm install -g @kintone/plugin-packer

パッケージ手順

以下の手順で、プラグインファイルをパッケージングします。

  1. マニフェストファイルに沿って、作成した各ファイルとマニフェストファイルを配置します。

  2. パッケージングしたいファイルをまとめたディレクトリー(src)の、ひとつ上のディレクトリーに移動します。
    上記のファイル配置例の場合、「work」に移動します。

    1
    
    cd work
  3. 次のコマンドを実行すると、自動でパッケージングが開始されます。
    実行に成功すると、成功メッセージが表示されます。

    1
    2
    3
    
    $ kintone-plugin-packer src
    
    Succeeded: DIRECTORY_PATH/work/plugin.zip
  4. 実行したディレクトリーに、プラグインファイル(plugin.zip)と秘密鍵ファイル(ppk ファイル)が生成されます。
    秘密鍵ファイルのファイル名は、プラグイン ID と同じです。
    次の例では、プラグイン ID が「faabchdodajloackbgnipilddblmkejp」です。

    秘密鍵ファイルは、2 回目以降のパッケージングで利用します。なくさないでください。

2回目以降のパッケージング

2 回目以降のパッケージングは、 --ppk オプションを使って、1 回目のパッケージングで生成された秘密鍵ファイルを指定します。
同じ秘密鍵ファイルを使ってパッケージングすると、プラグイン ID は同じになります。

1
kintone-plugin-packer --ppk PLUGIN_SECRET_KEY.ppk src

プラグインファイルの出力先ディレクトリーを変更したい場合や、ファイル監視しながらパッケージングしたい場合など、その他の機能については、 plugin-packer REAME の Options (External link) を参照してください。

kintone 環境へのインストール

作成したプラグインファイルを kintone へインストールします。

  1. 「kintone システム管理」を開きます。

  2. 「その他」の「プラグイン」をクリックします。

  3. 「読み込む」ボタンをクリックします。

  4. 「参照」ボタンをクリックし、パッケージ手順 4. で生成したプラグインファイル(plugin.zip)を選択します。

  5. 「読み込む」ボタンをクリックします。

  6. 「インストールされたプラグイン」に、作成したプラグインが表示されれば成功です。

補足

  • インストールできるプラグインファイルのサイズ上限値は、100MB です。
  • 同じプラグイン ID をもつプラグインファイルをアップロードすると、自動的に上書きインストールされます。
    そのプラグインを利用しているアプリにも即時適用されます。
  • アプリに複数のプラグインを適用する場合、プラグイン同士が競合し、意図しない挙動をすることがあります。
    運用に支障がないことを検証したうえで、プラグインを適用してください。

おわりに

今回は、パッケージツール(plugin-packer)を利用した kintone プラグインの作成手順と、kintone へのインストール方法について説明しました。

プラグインを使うと、kintone カスタマイズの内容を簡単に複数のアプリへ適用できます。
プラグインファイルのパッケージング手順も簡単なので、ぜひプラグイン作成に挑戦してみてください。

information

この Tips は、2019 年 1 月版 kintone で動作を確認しています。