kintone プラグイン開発手順

フォローする

Index

概要

kintoneプラグインを作成する場合はまず「はじめに」の記事を必ずご確認ください。kintone プラグイン作成の手順は以下です。

  1. kintone プラグインの作成に必要な各ファイルを作成します。
  2. kintone プラグインの作成に必要なマニフェストファイルを作成します。
  3. パッケージングツールを利用して、作成したファイルをパッケージングします。
  4. kintone環境にインポートします。

各ファイルの作成

まず初めに、パッケージングするファイルを準備していきます。パッケージングするためのフォルダ階層の作成及びファイル名は自由です。

フォルダ構成例

css/
  - customize.css //PC用CSSファイル
  - config.css //設定画面用CSSファイル
html/
  - config.html //設定画面用htmlファイル
image/
  - icon.png //アイコンファイル
js/
  - customize.js //PC用JavaScriptファイル
  - mobile-customize.js //スマートフォン用JavaScriptファイル
  - config.js //設定画面用JavaScriptファイル

アイコンファイル   

アプリの各画面で表示されるアイコン用ファイルです。

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

PC用JavaScriptファイル 

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

  • モバイル専用プラグインなどの場合省略することが可能です。
  • 設定画面から設定した情報を使い、実装したい処理を記述します。
  • ファイルサイズの上限値は、512KBまでです。
  • 設定画面のJavaScriptでkintone.plugin.app.setConfig()を利用して設定した情報は、kintone.plugin.app.getConfig()を利用して取得します。この際必要なプラグインIDは、kintone.$PLUGIN_IDという変数に出力されます。

※プラグインIDとは、プラグイン作成の際に各プラグインに一意に割り振られる32桁のIDです。 例:hkfgjeehkaajnbmfojmpbgcpfalbfhjn

 プラグインIDの参照例

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

PC用CSSファイル 

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

  • モバイル専用プラグインなどの場合省略することが可能です。
  • kintone のデザインを適用したい場合は、スタイルシートの利用をご利用ください。
  • ファイルサイズの上限値は、512KBまでです。

スマートフォン用JavaScriptファイル

スマート画面用のJavaScritpファイルです。

  • スマートフォンでプラグインを利用しない場合は、省略することが可能です。
  • 設定画面から設定した情報を使い、実装したい処理を記述します。
  • 設定画面のJavaScriptでkintone.plugin.app.setConfig()を利用して設定した情報は、kintone.plugin.app.getConfig()を利用して取得します。この際必要なプラグインIDの参照方法は、プラグインIDの参照例をご参考ください。
  • ファイルサイズの上限値は、512KBまでです。

設定画面用HTMLファイル

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

  • 省略することが可能です。
  • ファイルサイズの上限は64KBまでです。

設定画面用JavaScriptファイル 

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

設定画面用CSSファイル 

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

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

kintone プラグインの作成に必要なマニフェストファイルを作成します。
マニフェストファイル(manifest.json)はkintone プラグインの作成に必須です。

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

マニフェストファイルのフォーマットは以下です。json形式で各パラメータを指定していきます。

パラメータ名 必須 説明 制限 指定例
manifest_version Number
※整数のみ
必須 プラグインのマニフェストバージョン
1 を指定。
※現在有効なバージョンは 1 のみ。
 
"manifest_version": 1
version Number
※整数のみ
必須 プラグインのバージョン    
"version": 1
type String 必須 プラグインの種類。
文字列"APP"を指定。
   
"type":"APP"
name Object.<String> 必須 ロケール(ja, en, zh)をキーとする各言語のプラグイン名  
"name": { 
    "ja": "サンプルプラグイン",
    "en": "sample plugin",
    "zh": "插件的例子"
  }
name.<locale> String 必須 指定されたロケールのプラグイン名 1文字以上64文字以下。name.enは必須
description Object.<String> 省略可 ロケールをキーとする各言語の説明文  
"description": { 
    "ja": "これはサンプルプラグインです。",
    "en": "This is sample plugin.",
    "zh": "这是插件的例子"
  }
description.<locale> String 必須 指定されたロケールの説明文 1文字以上200文字以下。descriptionがある場合、description.enは必須
icon String 必須 アイコンファイル プラグイン内のファイルのみ指定可能
"icon": "image/sample.png"
homepage_url Object.<String> 省略可 ロケールをキーとする各言語のWebサイトURL    
"homepage_url": { 
    "ja": "http://sample_cybozu.jp",
    "en": "http://sample_cybozu.com",
    "zh": "http://sample_cybozu.cn"
  }
homepage_url.<locale> String 省略可 指定されたロケールのWebサイトURL  
desktop Object.<String> 省略可  ファイルの種類(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 Array.<String> 省略可 PC用JavaScriptファイル・URLの配列

30個まで
※同名のファイルがある場合エラーになります。

desktop.css Array.<String> 省略可  PC用CSSファイル・URLの配列 30個まで
※同名のファイルがある場合エラーになります。
mobile Object.<String> 省略可  ファイルの種類(js)をキーとするスマートフォン用カスタマイズファイル  
"mobile": {
    "js": [
      "js/mobile-customize.js",
      "https://example.com/js/mobile-customize.js"
    ]
  }
mobile.js Array.<String> 省略可  スマートフォン用JavaScriptファイル・URLの配列 30個まで
※同名のファイルがある場合エラーになります。
config Object.<String> 省略可  ファイルの種類(html, js, 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"]
  }
}
config.html String 省略可  設定画面用HTMLファイル プラグイン内のファイルのみ指定可能
config.js Array.<String> 省略可  設定画面用JavaScriptファイル・URLの配列 30個まで
※同名のファイルがある場合エラーになります。
config.css Array.<String> 省略可  設定画面用CSSファイル・URLの配列 30個まで
※同名のファイルがある場合エラーになります。
config.required_params Array.<String> 省略可  設定画面で設定必須なパラメータの配列 ASCIIで1文字以上64文字以下。

マニフェストファイル例

パッケージング

作成した各ファイルとマニフェストファイルを、パッケージングするためにマニフェストファイルに沿ってファイルを配置します。

ファイル配置例

css/
  - customize.css //PC用CSSファイル
  - config.css //設定画面用CSSファイル
html/
  - config.html //設定画面用htmlファイル
image/
  - icon.png //アイコンファイル
js/
  - customize.js //PC用JavaScriptファイル
  - mobile-customize.js //スマートフォン用JavaScriptファイル
  - config.js //設定画面用JavaScriptファイル
manifest.json //マニフェストファイル

次に、パッケージングツールを利用してパッケージングを下記の手順で行います。

取得したパッケージングツールを配置します。

例:/work/

パッケージングツールを配置したフォルダに移動します。

コマンド例:
$cd /work/

パッケージングツールを実行します。第一引数として、マニフェストファイルが置かれているフォルダを指定します。

コマンド例:
$package.sh <manifest.jsonが置かれているフォルダ>

成功すると、実行したフォルダに以下のフォルダとファイルが作成されます。※プラグインIDが「hkfgjeehkaajnbmfojmpbgcpfalbfhjn」の時の例

keys/
  - check_plugin.hkfgjeehkaajnbmfojmpbgcpfalbfhjn.ppk //秘密鍵ファイル
plugins/
/hkfgjeehkaajnbmfojmpbgcpfalbfhjn
  - plugin.zip //パッケージファイル

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

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

2回目以降のパッケージングは、以下のように秘密鍵ファイルも指定してください。

コマンド例:
$package.sh <manifest.jsonが置かれているフォルダ> <はじめてのパッケージングで生成された秘密鍵ファイル>

※パッケージングについてはツールのインストールや初期設定が必要になるので、プラグイン開発でつまづきやすいポイントの記事も参照してください。

インポート

プラグインの管理画面より、「読み込む」ボタンを押して手順3で作成したパッケージファイル「plugin.zip」をkintone環境にインポートします。「インストールされたプラグイン」に作成したプラグインが表示されれば完了です。

 

  • インポートできるファイルのサイズは100MBまでです。

補足

  • 同じプラグインIDのものをアップロードすると、自動的に上書きインストールされ、利用中のアプリにも即時適用されます。
  • 一つのアプリに複数のプラグインを設定している場合、カスタマイズを充てているフィールドが被るとプラグイン同士が競合して挙動がおかしくなる可能性があります。
    (対策例)
    どうしても同時に使いたい場合は、複数のプラグインのコードファイルを1ファイルにまとめて、Promiseでつないで処理を記述するという方法があります。Promise処理についてはこちらの記事を参照してください。

記事に関するフィードバック

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

Avatar
ponkichi31
ponkichi31により編集されました
Avatar
Takashi Hosoya

「customize.js.js 」と拡張しが二つ付いている箇所があります!

Avatar
cybozu Development team

To Hosoya san

フォルダ構成の部分で、誤記がありましたので修正しました。
ご報告をいただきましてありがとうございます。

Avatar
Takashi Hosoya

kintone.plugin.getConfig(PLUGIN_ID);  の記述があります!
正しくは、「kintone.plugin.app.getConfig(PLUGIN_ID);」かなと思います!

Avatar
cybozu Development team

Hosoya さま

PC用JavaScriptファイル > プラグインIDの参照例

の箇所で kintone.plugin.getConfig(PLUGIN_ID); の記述があったため、

「kintone.plugin.app.getConfig(PLUGIN_ID);」に修正いたしました。ご指摘をありがとうございます。

ログインしてコメントを残してください。
Powered by Zendesk