Welcome to AsakusaSatellite’s documentation!¶
Contents:
セットアップ¶
動作環境¶
以下のソフトウェアのインストールが必要です。
- Ruby 1.8.7 / 1.9.3 / 2.0.0 / 2.1.0 or JRuby 1.7.1
- RubyGems 1.4.2 or later
- Bundler 1.0.7 or later
- MongoDB 1.8.1 or later
インストール¶
以下では、3つの場合のインストール方法について説明します。
- Windows以外のOS(単体起動)
- Windows以外のOS(PassengerによるApacheとの連携)
- Windows
Windows以外のOS(単体起動)¶
ダウンロードリンク から最新版をダウンロードし、適当なディレクトリに展開してください。 展開したディレクトリを AsakusaSatellite にリネームし、以下のコマンドを実行してください。
# MongoDBの起動(起動済みの場合は不要)
$ mongod --dbpath <dir_name>
# 展開ディレクトリへの移動
$ cd AsakusaSatellite
# 依存ライブラリのインストール
$ bundle install --path .bundle --without development test
# リソースのプリコンパイル (0.8 以降)
$ bundle exec rake assets:precompile RAILS_ENV=production
# WebSocketサーバ、AsakusaSatellite本体の起動
$ bundle exec thin -R socky/config.ru -p3002 -t0 start &
$ bundle exec rails server -e production
localhost 以外で運用する場合には、WebSocket サーバの設定を変更してください。 config/message_pusher.yml の localhost を IP アドレス等で置換してください。
socky:
http: http://localhost:3002/http
http: ws://localhost:3002/websocket
app: as
secret: secret
設定の反映には、AsakusaSatellite の再起動が必要です。
Windows以外のOS(PassengerによるApacheとの連携)¶
設定ファイルの修正
config/environments/production.rb を編集して serve_static_assets の値を以下のとおり修正します。
config.serve_static_assets = false
リソースのプリコンパイル (0.8 以降)
以下のコマンドを実行します。
$ bundle exec rake assets:precompile RAILS_ENV=production
Passenger のインストール
gem から Passenger をインストールします。
$ gem install passenger
Apacheモジュールをビルドします。
$ passenger-install-apache2-module
Apacheの設定ファイルへの記述が表示されるのでメモを取ります。
例)
LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-2.2.11/ext/apache2/mod_passenger.so
PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-2.2.11
PassengerRuby /usr/bin/ruby1.8
必要なパッケージのインストールを促された場合、 指示にしたがってインストールの後再実行してください。
Apache の設定
Apache への設定に以下を記述します。
RailsEnv production
RailsBaseURI /as
DocumentRoot に AsakusaSatellite の public ディレクトリへのシンボリックリンクを作成します。
例)
- DocumentRoot が /var/www
- AsakusaSatellite が /var/AsakusaSatellite
にインストールされている場合
$ cd /var/www
$ sudo ln -s /var/AsakusaSatellite/public as
Apacheの再起動の後、http://hostname/as でアクセスできるようになります。
Windows¶
以下の Ruby での動作を確認しています。
- Ruby 1.8.7 (http://rubyinstaller.org/downloads/)
また、以下のアドオンのインストールが必要です。
- DevKit (http://rubyinstaller.org/downloads/)
それ以外は、Windows 以外の OS の場合と同じです。
対応ブラウザ¶
AsakusaSatellite は以下のブラウザをサポートしています。
- Google Chrome
- Safari
また、制限付きで以下のブラウザをサポートしています。
- Mozilla Firefox
- Opera
Google Chrome¶
すべての機能をご利用可能です。
Safari¶
バージョン 6.0 以降ですべての機能をご利用可能です。
Mozilla Firefox¶
バージョン 4 からのサポートです。 WebSocket を有効にするために、以下の設定を行ってください。 (バージョン 7 以降ではこの設定は不要です)
- アドレスバーに “about:config” と入力します。
- network.websocket.override-security-block の値を “true” に変更します。
以下の機能がご利用いただけません。 (アドオンをインストールすればご利用いただけます)
- デスクトップ通知
Opera¶
バージョン 11 からのサポートです。 WebSocket を有効にするために、以下の設定を行ってください。
- アドレスバーに “about:config” と入力します。
- “User Prefs” の “Enable WebSockets” をチェックします。
- “保存” をクリックします。
以下の機能がご利用いただけません。
- デスクトップ通知
- ファイルアップロード
Heroku へのデプロイ¶
AsakusaSatellite は Heroku (Cedar Stack) 上で動作させることができます。 以下、Heroku へのデプロイの手順について説明します。
なお、手順では以下を前提とします。
- heroku gem および git がインストールされていること
- Heroku のアカウントを持っていること
- Githubのページ から最新の ZIP をダウンロードし展開します。
- AsakusaSatellite を git の管理下に置きます。
AsakusaSatellite のトップディレクトリにて以下のコマンドを発行します。
$ git init
$ git add .
$ git commit -a -m "heroku"
- Heroku にアプリケーションを作成します。
AsakusaSatellite のトップディレクトリにて以下のコマンドを発行します。
$ heroku create
Creating nameless-sands-3102... done, stack is cedar
http://nameless-sands-3102.herokuapp.com/ | git@heroku.com:nameless-sands-3102.git
Git remote heroku added
- MongoDB Add-on を追加します。
$ heroku addons:add mongohq:sandbox
----> Adding mongohq:sandbox to nameless-sands-3102... done, v2 (free)
- MongoDB の設定をします。
追加された MongoDB の設定を確認します。
$ heroku config | grep MONGOHQ_URL
MONGOHQ_URL => mongodb://heroku:e027fb5a44f9bb34beeb7318f0f1bd7f@staff.mongohq.com:10025/app8004619
確認した設定を元に、以下の環境変数を設定します。
- MONGODB_HOST
- MONGODB_PORT
- MONGODB_DATABASE
- MONGODB_USERNAME
- MONGODB_PASSWORD
$ heroku config:add MONGODB_HOST=staff.mongohq.com MONGODB_PORT=10025 MONGODB_DATABASE=app8004619 MONGODB_USERNAME=heroku MONGODB_PASSWORD=e027fb5a44f9bb34beeb7318f0f1bd7f
- Pusher Add-on を有効にします。
$ heroku addons:add pusher:sandbox
----> Adding pusher:sandbox to nameless-sands-3102... done, v4 (free)
- Pusher の設定をします。
追加された Pusher の設定を確認します。
$ heroku config | grep PUSHER_URL
PUSHER_URL => http://b217da9d38540ccd56fd:a3039bb476ae56d2b631@api.pusherapp.com/apps/28676
以下の環境変数を設定します。
- MESSAGE_PUSHER_ENGINE
- MESSAGE_PUSHER_PUSHER_APP_ID
- MESSAGE_PUSHER_PUSHER_KEY
- MESSAGE_PUSHER_PUSHER_SECRET
$ heroku config:add MESSAGE_PUSHER_ENGINE=pusher MESSAGE_PUSHER_PUSHER_APP_ID=28676 MESSAGE_PUSHER_PUSHER_KEY=b217da9d38540ccd56fd MESSAGE_PUSHER_PUSHER_SECRET=a3039bb476ae56d2b631
- Heroku へデプロイします。
$ git push heroku master
- デプロイが完了したアプリケーションにアクセスします。
$ heroku open
基本機能¶
部屋作成¶
- トップページで Create New Room ボタンをクリックします

- 部屋名を入力し、 Create ボタンをクリックします。 このとき public room のチェックをはずすと、参加者のみに公開される非公開部屋を作成できます。 参加者の追加・削除は部屋の設定画面から行なえます。

- 部屋が作成されます。

作成した部屋を削除するためには、部屋を表示し、 部屋名の右にある削除アイコンをクリックします。

部屋の設定変更¶
部屋の設定を変更するためには、部屋を表示し、 部屋名の右にある設定アイコンをクリックします。

設定項目は以下の通りです。
- 部屋名 (必須): 部屋の名称を指定します。
- ニックネーム (任意、0.8.1 以降):
部屋のニックネームを指定します。ニックネームにはアルファベットおよび “-”, “_” が使用できます。
- ニックネームを指定しない場合: 部屋へのリンクが http://hostname/chat/room/<ID> となります
- ニックネームを指定した場合: 部屋へのリンクが http://hostname/chat/room/<ニックネーム> となります
- メンバー (秘密の部屋の場合): この部屋に参加できるメンバを指定します。

設定変更後、 Update Config ボタンをクリックすることで、設定が保存されます。
また画面の下半分はプラグインの設定画面へのリンクです。 Configuration リンクをクリックすることで、プラグインの設定ページに移動できます。

チャット¶
- トップページで部屋を選択します

- 一番下のテキストボックスに発言内容を記入し、 Send ボタンをクリックします。

- 発言内容が末尾に追加され、他の閲覧者に通知されます。

ブラウザがチャットサーバに正しく接続できているかは アイコンの表示で確認できます。 削除ボタンのアイコンに×マークが表示されている場合には 正しく接続できていないため、 インストールが正しく行われているかを確認してください。

マウスポインタを発言の上にかざすと その発言を編集するボタンが表示されます。

左から順に以下の意味を持っています。
- Redmine チケット作成ボタン(プラグイン)
- 発言編集ボタン
- 発言削除ボタン
自分以外のユーザのメッセージは編集と削除ができません。
ファイルアップロード¶
- チャット画面にファイルをドラッグ&ドロップします。

2. ファイルがアップロードされ、そのファイルへのリンクを表示します。 ドラッグしたファイルが画像の場合、その画像を表示します。

デスクトップ通知¶
閲覧中の部屋で自分以外のメッセージが投稿された場合に、 デスクトップに通知します。

デスクトップ通知を有効にするには、設定を行う必要があります。 画面右上のログインユーザのリンクをクリックし、個人設定画面を開きます。 Desktop Notification On をクリックし、 その後、 許可 をクリックしてください。

表示時間を設定する場合は、 Notification time in second(s) の値を 変更し、 Set をクリックしてください。 デフォルトは3秒です。0秒に設定すると、通知は表示されたままになります。 OS X の通知センターをご利用の場合は、0秒に指定すると便利です。
許可を解除するためには、Google Chrome のアドレスバーに
chrome://settings/contentExceptions#notifications
と入力し、設定を行ってください。
全文検索¶
- トップページの検索ボックスに探したい単語を入力し、 Search ボタンをクリックします。

- 検索結果が表示されます。検索結果の近くの発言を閲覧する場合は日付をクリックします。

- 検索結果の前後の発言を表示します。

バージョンの確認¶
- 各ページのフッターにある AsaksuaSatellite リンクをクリックします。

- 現在のAsakusaSatelliteのバージョン、および主要ライブラリのバージョンが表示されます。

本体の設定¶
config/settings.yml においてAsakusaSatellite本体の挙動を変更できます。
認証¶
- omniauth
- 認証方法を指定します。 詳しくは 認証方法の変更 (0.8.1 以降) を参照してください。
ファイル添付¶
- attachment_policy
- 添付ファイルの保存方法を指定します。 詳しくは watage を参照してください。
- attachment_path
- 添付ファイルの保存先を指定します。
- attachment_max_size
- 添付ファイルの上限サイズをバイト単位で指定します。 指定しない場合や0を指定した場合は無制限になります。
- watage_xxxx
- watageプログインの設定を指定します。 詳しくは watage を参照してください。
WebSocketサーバの変更¶
<AS_ROOT>/config/message_pusher.yml により、AsakusaSatelliteで利用するWebSocketサーバを変更できます。
現時点ではSocky, Pusher, Keima の 3 方式をサポートしています。
Pusher¶
Pusher ( http://pusher.com ) を利用して通信します。
設定方法¶
http://pusher.com に登録して、app_id, key, secretを取得します。
<AS_ROOT>/config/message_pusher.yml を以下のように編集します。
default: pusher
engines:
# pusherの設定
pusher:
app_id: <your app id>
key: <your key>
secret: <your secret>
AsakusaSatellite を再起動することで設定が反映されます。
利点・欠点¶
有料プランを利用すれば多数のユーザの同時使用にも耐えることができます。 また、WebSocketだけでなくFlashSocketによる接続も可能なため、WebSocket非対応のブラウザからも利用できます。
ただし、外部サービスを利用するため、社内での利用等には向きません。
Keima¶
Pusher クローンである Keima ( https://github.com/codefirst/keima ) を利用して通信します。
設定方法¶
keima にアクセスし、appkey を取得します。
<AS_ROOT>/config/message_pusher.yml を以下のように編集します。
default: keima
engines:
url: <your keima url>
key: <your key>
AsakusaSatellite を再起動することで設定が反映されます。
利点・欠点¶
社内のネットワーク等に設置した Keima を利用できるため、セキュリティを確保することができます。
また、Pusher 利用時と同様に、WebSocket 非対応のブラウザからも利用が可能です。
プラグイン¶
設定ファイルについて¶
AsakusaSatellite は、環境変数 FILTER_NAME に指定された名前のファイルを <AS_ROOT>/config/ 配下から読み込み、プラグインの設定を行います。 環境変数 FILTER_NAME が指定されない場合には、filter_intra.yml というファイルが利用されます。 このファイルは、イントラネットで AsakusaSatellite をご利用いただくのに適した設定になっています。
以下ではそのファイルの内容についての説明をします。
v0.8.0 以前¶
<AS_ROOT>/plugins/ 配下に置かれたプラグインは、基本的にすべて有効になります。 フィルタは、適用される順序を指定することができます。 フィルタとは、メッセージを加工するためのプラグインで、 AsakusaSatellite::Filter::Base を継承したものです。
設定ファイルの内容は例えば以下のようになります。
- name: code_highlight_filter
- name: quote_it
- name: redmine_ticket_link
- name: twitter_link
- name: emoji_filter
値にはフィルタのクラス名をスネークケースに変換したものを指定します。 メッセージの加工は、上から書かれた順に実行されます。 設定ファイルに書かれなかったフィルタは適用されません。
v0.8.1 以降¶
<AS_ROOT>/plugins/ 配下に置かれたプラグインは、置くだけでは有効になりません。 設定ファイルにプラグインを記述することで初めて有効になります。
設定ファイルの内容は例えば以下のようになります。
info:
version: 2
filters:
- name: code_highlight_filter
- name: auto_link
- name: redmine_ticket_link
- name: twitter_link
- name: emoji_filter
plugins:
- dir: as_twitterauth_plugin
filters には、v0.8.0 以前でも設定したように、フィルタの適用順序を記載します。 plugins には、フィルタではないプラグインの中で有効にしたいプラグインを指定します。 フィルタではないプラグインとは、ビューフックや認証プラグインのことを指します。
プラグインの指定方法は二種類あります。
dir キーを指定した場合には、プラグインのディレクトリ名を指定します。
plugins:
- dir: as_twitterauth_plugin
name キーを指定した場合には、フィルタのクラス名をスネークケースに変換したものを指定します。 ただしこの場合、プラグインのディレクトリ名は、 as_<フィルタのクラス名をスネークケースに変換したもの> という名前になっている必要があります。 この規約が守られていない場合も、以下の例のように name と dir を同時に指定することでディレクトリを指定して、フィルタを有効にすることができます。
filters:
- name: auto_link
dir: as_autolink
なお、v0.8.1 以降でも v0.8.0 の設定ファイルのフォーマットを利用することができます。 その場合は、プラグインの読み込みの挙動は v0.8.0 と同等の動きをします。
デスクトップ通知¶
設定¶
config/filter_intra.yml に以下を記述します
- dir: as_desktopnotification
また、部屋ごとに通知の有効無効を設定できます。 画面右上のログインユーザのリンクをクリックし、 Settings for each rooms で部屋名の右のボタンをクリックしてください。
- Notification On と表示されている部屋はデスクトップ通知が有効です。
- Notification Off と表示されている部屋はデスクトップ通知が無効です。

Redmine 連携¶
機能¶
#数字 を Redmine のチケットへのリンクに変換します。 API アクセスキーが設定されている場合は、チケットの名前を自動で付加します。 また、メッセージの内容を Redmine に投稿するためのリンクを各メッセージに付加します。
設定¶
config/filter_intra.yml に以下を記述します
- name: redmine_ticket_link
また部屋の設定画面からRedmineのルートURL、APIアクセスキー、チケットを作成するプロジェクトを指定できます。 APIアクセスキーはRedmineの”個人設定 > API アクセスキー”から確認できます。

コードハイライト¶
機能¶
ソースコードをハイライトします。 記法は
- 1行目に 言語::
- 2行目以降に ソースコード を記述します。
例えば,
ruby::
puts "Hello World!"
と記述することで、2行目がハイライトして表示されます。
また、Graphviz の dot 記法もサポートしています。
graphviz::
digraph{A->B->C->A}
のように、 graphviz:: に続けて dot 記法を記述することで 簡単なグラフを描画することができます。
汎用リンク¶
QuoteItプラグイン¶
絵文字プラグイン¶
機能¶
メッセージ中の :絵文字名: を画像として展開します。 また、メッセージを入力中に ”:” を入力すると、利用可能な絵文字をサジェストします。
設定¶
config/filter_intra.yml に以下を記述します
- name: emoji_filter
利用可能な絵文字の一覧は、 Emoji cheat sheet をご参照ください。

emoticon プラグイン¶
機能¶
ルールベースでメッセージの変換を定義し、画像として展開します。
設定¶
- config/filter_intra.yml の filter 要素の下に以下を記述します。
- name: emoticon_filter
- plugins/as_emoticon_filter/rule.yml を編集し、変換ルールを作成します。
- <AS_ROOT>/public/emoticons に rule.yml で指定したファイル名で emiticon ファイルを保存します。
rule.yml は yaml 形式でキーにメッセージの変換対象、値に変換後に表示するファイル名を記述します。
例えば、rule.yml に
- (test): test.gif
と記述した場合は <AS_ROOT>/public/emoticons/test.gif に画像ファイルを保存し、メッセージ中に (test) と記述することで画像が展開されます。
CSS/Javascriptプラグイン¶
機能¶
すべてのページに指定されたスタイルシート・Javascriptを挿入することで、簡単に機能拡張できるようにします。
拡張例¶
- 未読件数表示(https://gist.github.com/4189242)
- faviconにメッセージの未読件数を表示します。
ローカル認証¶
機能¶
AsakusaSatellite は Twitter の OAuth を用いて認証を行いますが、 本プラグインを有効にすると、ローカルのユーザリストを用いた認証に切り替えます。
設定¶
config/filter_intra.yml の plugins 要素の下に以下を記述します
- dir: as_localauth_plugin
<AS_ROOT>/config/settings.yml に以下を記述します。 本設定を行うことにより、Twitter の OAuth による認証は無効になり、 ローカル認証が有効になります。
omniauth:
provider: "local"
次に、ユーザリストにユーザを追加します。 ユーザリストは以下のファイルです。
<AS_ROOT>/plugins/as_localauth_plugin/config/users.yml
内容は以下の形式です。
testuser1:
screen_name: Test User1
password: b444ac06613fc8d63795be9ad0beaf55011936ac
profile_image_url: http://example.com/test1_user.png
ユーザリストは YAML 形式で記述します。
testuser1 の部分 にはユーザ ID を記述します。
screen_name はユーザの表示名を記述します。
password にはパスワードの SHA-1 ハッシュを記述します。 SHA-1 ハッシュの生成は、以下のコマンドで行うことができます。
$ ruby <AS_ROOT>/plugins/as_localauth_plugin/script/gen_sha1 <PASSWORD>
profile_image_url にはユーザのアイコンの URL を記述します。 データ URI スキームも指定することもできます。 testuser2 の例を参考にしてください。
Redmine API アクセスキー認証¶
設定¶
config/filter_intra.yml の plugins 要素の下に以下を記述します
- dir: as_redminelauth_plugin
<AS_ROOT>/config/settings.yml に以下を記述します。
omniauth:
provider: 'redmine'
provider_args:
- 'Redmine の URL'
使用方法¶
- 「ログイン」リンクをクリックします。
- 以下の情報を入力します
- RedmineのAPIアクセスキー
- AsakusaSatellite で使用するユーザ名
- AsakusaSatellite で使用する画像の URL
- ログインボタンをクリックします。
private な部屋に追加するときの注意点¶
このプラグインで認証されたユーザは、ユーザ ID として Redmine のユーザの メールアドレス が保存されます。 したがって、private に設定された部屋にこのプラグインで認証されたユーザを追加する場合は、Redmine のユーザの メールアドレス を指定する必要があります。
Watage プラグイン¶
機能¶
AsakusaSatellite を Heroku にデプロイした場合、 Heroku の制限により、ファイルアップロード機能が利用できません。
そこでストレージサービスの汎用インタフェースである Watage を利用し、添付ファイルをDropboxなどのクラウドストレージ上に保存するプラグインです。
Watage の詳細については、 Watage のドキュメント を参照ください。
設定¶
config/filter_intra.yml の plugins 要素の下にに以下を記述します
- dir: as_watage_plugin
token/secret tokenをWatageから取得した上で、config/settings.yml に以下を記述します。
attachment_policy: watage
attachment_path: <WatageのURL(例: http://watage.examlpe.com/)>
watage_token: <your watage token>
watage_token_secret: <your watage token secret>
プラグインの作成¶
AsakusaSatellite はプラグインを作成することにより、 機能を拡張することができます。 以下の三種類の拡張方法があります。
- メッセージフィルタ
- メッセージを変換するフィルタ機能を追加する拡張方法です。 例えば、URL をリンクに変換することができます。
- ビューフック
- チャットページの決められた場所に、HTML を追加する拡張方法です。 例えば、各発言に好きなボタンを追加することができます。
- 認証方法の変更
- AsakusaSatellite へのログインに利用する認証を変更する拡張方法です。 例えば、認証を Github の OAuth に変更することができます。
メッセージフィルタ¶
フィルタプラグイン生成コマンド¶
ジェネレータが用意されています。
$ rails g as_filter フィルタ名
とすることで plugins/as_フィルタ名_filter に以下に以下のように生成されます。
- init.rb: プラグインの初期設定
- lib/フィルタ名_filter.rb: フィルタプログラム
- spec/lib/フィルタ名_filter_spec.rb: フィルタのテスト
フィルタの登録¶
フィルタの登録は config/filter_infra.yml で行います。 登録されたフィルタは、上から順番に適用されます。
- name: フィルタ名_filter
任意の名前で引数を与えることもできます。
- name: フィルタ名_filter
url: xxx
フィルタプログラム¶
フィルタプログラムは AsakusaSatellite::Filter::Base を継承したクラスを作成し、 process メソッドを実装します。 (ジェネレータで生成した場合は lib/フィルタ名_filter.rb に生成されています。) フィルタ設定で与えた引数はAsakusaSatellite::Filter::Base を継承したクラスでは config 変数で保持しています。
class XxxFilter < AsakusaSatellite::Filter::Base
# メッセージを処理します
# text: メッセージの本文
# return: フィルタしたメッセージ
def process(text)
%[<a target="_blank" href="#{config.url}">#{text}</a>]
end
end
ビューフック¶
ビューフックとは¶
ビューフックは AsakusaSatellite のビュープログラムに あらかじめ設定されたフックポイントにプラグインからHTMLを 埋め込んで画面を拡張する仕組みです。
ビューフックを使用して画面を拡張するには AsakusaSatellite::Hook::Listener を継承したクラスを実装します。
AsakusaSatellite::Hook::Listener を継承したクラスはRailsの起動時に読み込まれ、 自動的に登録されます。
ビューフックプラグイン生成コマンド¶
ジェネレータが用意されています。
$ rails g as_viewhook プラグイン名
とすることで plugins/as_プラグイン名 に以下に以下のように生成されます。
- init.rb: プラグインの初期設定
- lib/プラグイン名.rb: ビューフックプログラム
- spec/lib/プラグイン名_spec.rb: ビューフックのテスト
ビューフックリスナの作成¶
作成コマンドを発行し、プラグインのテンプレートを生成します。
ここでは test_listener とします
$ rails g as_viewhook test_listener
plugins/as_test_listener/lib/test_listener.rb を以下のように編集します。
class TestListener < AsakusaSatellite::Hook::Listener
def message_buttons(context)
if context[:message].body
context[:message].body.size.to_s + "文字"
else
"0文字"
end
end
end
リスナクラスでAsakusaSatelliteに設置されているフックポイント名と同名の メソッドを実装します(上記の例ではmessage_buttons) 。引数(context)はビューフックから 渡されてくるオブジェクトを保持するハッシュが渡されます。
フックポイントの調べ方¶
フックポイントを調べるには、view の中で call_hook を呼んでいる 箇所を検索することができます。 具体的には、以下のコマンドが利用できます。
$ git grep call_hook app/views
現在のバージョンでは、以下のフックポイントが有効です。
- chat_room_top
- チャットルームの上部に HTML を差し込みます
- chat_room_bottom
- チャットルームの下部に HTML を差し込みます
- message_buttons
- 各発言のボタンが表示される箇所に HTML を差し込みます
- account_setting_item(0.8.1以降)
- 個人設定画面に HTML を差し込みます
- global_setting_item(0.8.1以降)
- Aboutページに HTML を差し込みます
- global_header(0.8.1以降)
- すべてのページの上部に HTML を差し込みます。
- global_footer(0.8.1以降)
- すべてのページの下部に HTML を差し込みます。
assetファイル(画像、CSS等)の公開 (0.8.1以降)¶
plugins/<plugin>/app/assets/<type>/<filename> にファイルを配置すると、 /plugin/<plugin>/<type>/<filename> でアクセスできるようになります。
例えば plugins/as_hoge/app/assets/stylesheets/style.css にファイルを配置すると /plugin/as_hoge/stylesheets/sytle.css でアクセスできます。
認証方法の変更 (0.8.1 以降)¶
OmniAuth による認証の切り替え¶
AsaksuaSatellite へのログイン時の認証は OmniAuth を使用しています。 デフォルトではプロバイダとして Twitter の OAuth を利用していますが、プラグインを追加することで切り替えが可能となっています。
既存の OmniAuth Strategy を使用した認証の切り替え¶
公開されている OmniAuth Strategy を利用することで、認証プラグインを作成することができます。
以下、プラグインの作成手順について説明します。
- プラグインの作成
<AS_ROOT>/plugins ディレクトリの直下に任意のディレクトリを作成し、その直下に Gemfile を以下のとおり作成します。
gem 'omniauth-XXXX' # 利用する OmniAuth Strategy の gem
例えば、 Github の OAuth による認証 を利用する場合は以下のようになります。
gem 'omniauth-github'
- 依存 gem の再インストール
<AS_ROOT> ディレクトリに移動し、以下のコマンドを入力して、依存 gem をインストールしなおします.
$ bundle install --path .bundle --without development test
- 設定
<AS_ROOT>/config/settings.yml の “omniauth” の設定項目を修正して AsakusaSatellite で利用する認証を変更します。
omniauth:
provider: "プロバイダ"
provider_args:
- "引数1"
- "引数2"
- "..."
設定内容は以下の通りです。
- provider (必須): 使用する OmniAuth Strategy の名称を記述します。
- provider_args (任意): 使用する OmniAuth Strategy の設定時に渡される引数を配列で指定します。
例えば Github の OAuth による認証を利用する場合は以下のとおりとなります
omniauth:
provider: "github"
provider_args:
- "<Client ID>"
- "<Client Secret>"
provider と provider_args に渡す値については各 OmniAuth Strategy を参照してください。
- AsakusaSatellite の再起動
AsakusaSatellite を再起動することで認証が切り替わります。
既存の OmniAuth Strategy を使用しているプラグインは以下の通りです。
独自 OmniAuth Strategy による認証¶
OmniAuth Strategy を自作することが可能です。
独自 OmniAuth Strategy 作成の詳細については Strategy Contribution Guide を参照してください。
以下、プラグインの作成手順について説明します。
- OmniAuth Strategy クラスを作成する.
OmniAuth の規約にしたがって OmniAuth::Strategies モジュール以下にクラスを作成します。 <AS_ROOT>/plugins ディレクトリの直下に任意のディレクトリを作成し、lib/omniauth/strategies/mystrategy.rb を以下のように作成します。
module OmniAuth
module Strategies
class Mystrategy
include OmniAuth::Strategy
args [:arg1, :arg2] # provider_args で渡される引数
def request_phase
...
end
def callback_phase
...
end
info {
{:name => '....', :nickname => '....', :image => 'http://....'}
}
end
end
end
OmniAuth Strategy に従い、info で取得できる値を作成します。
AsakusaSatellite で使用する値は :name, :nickname および :image です。 それぞれの意味は以下の通りです。
- :name : ユーザを一意に識別する ID として使用します。
- :nickname : ユーザの表示名として使用します。
- :image : ユーザの発言などに付加される画像ファイルの場所を特定するために使用します。
AsakusaSatellite プラグインは、 app ディレクトリ以下に Rails の controller, view を独自に作成できるため、 request_phase メソッドの実装で独自に作成したページにリダイレクトすることにより、独自の認証フォームを作成することも可能です。
- 独自 Strategy を読み込む
プラグインディレクトリの直下に init.rb ファイルを以下のように作成します。
require 'omniauth/strategies/mystrategy'
- 設定
<AS_ROOT>/config/settings.yml の “omniauth” の設定項目を修正して AsakusaSatellite で利用する認証を変更します。
omniauth:
provider: "mystrategy" # Strategy 名
provider_args: # Strategy に渡す値
- "引数1"
- "引数2"
- AsakusaSatellite の再起動
AsakusaSatellite を再起動することで認証が切り替わります。
独自 OmniAuth Strategy を使用しているプラグインは以下の通りです。
UserScript で AsakusaSatellite のイベントを取得する方法 (0.8.1 以降)¶
AsakusaSatellite は、UserScript が安全にクロスドメイン制約を回避できるようにするため、 window.postMessage を用いて各種イベントを通知します。
通知されるイベントの種類と含まれる情報¶
通知されるイベントは type, current, data の3つの情報を持っています。 current には現在の部屋の ID とユーザの ID が含まれます。 data の内容は type に応じて変化します。
type の種類と、data に含まれる情報は以下です。
- connect
- websocket サーバとの接続が確立した際に通知されます。 使用している websocket サーバにより含まれる情報は異なります。
- error
- websocket サーバとの接続でエラーが発生した際に通知されます。 使用している websocket サーバにより含まれる情報は異なります。
- disconnect
- websocket サーバとの接続が切断された際に通知されます。 使用している websocket サーバにより含まれる情報は異なります。
- create
- 新規メッセージを受信した際に通知されます。 新着メッセージの全情報が含まれます。詳しくは Message モデルを参照ください。
- update
- メッセージ更新された際に通知されます。 新着メッセージの全情報が含まれます。詳しくは Message モデルを参照ください。
- delete
- メッセージが削除された際に通知されます。 削除されたメッセージの ID が含まれます。
イベントハンドラのサンプル¶
以下のように message イベントに対してイベントハンドラを登録し、 イベント内の type の値で処理を切り替えてください。
window.addEventListener('message', function(e){
switch(e.data.type) {
case "create":
...
case "update":
...
}
});
API¶
本章では、AsakusaSatellite が提供している API について説明します。 外部のアプリケーションから、AsakusaSatellite に 発言を投稿したり、発言を取得したりすることができます。
API キー¶
API キーは、API を利用するために使用する認証用のキーです。 キーを利用することで、AsakusaSatellite は ユーザを認証することができます。 そのため、API キーは他人に渡してはいけません。
API キーを取得するには、 画面右上のログインユーザ名のリンクをクリックし、 個人情報画面を開きます。

画面に表示されているランダムな文字列が、 ログインユーザを認証するための API キーです。
Generate ボタンをクリックすると再生成します。
RESTful API¶
メソッドについて¶
PUT 及び DELETE に対応していないライブラリでは、 パラメータに _method=put または _method=delete を 付加して POST することで同じ動作をさせることができます。
発言の操作 API¶
発言の表示
- URL: /api/v1/message/id.format
- id (必須) … メッセージの ID を指定します
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: GET
- パラメータ:
- api_key (private room の場合必須) … ユーザの API キーを指定します。private room のメッセージの取得は 0.8.0 以降の対応となります。
- URL: /api/v1/message/id.format
発言の作成
- URL: /api/v1/message.format
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: POST
- パラメータ:
- room_id (必須) … 発言を作成する対象となる部屋の ID もしくはニックネームを指定します
- message (必須) … 発言内容の文字列を指定します
- files (任意) … 添付するファイルのパスを指定します
- api_key (必須) … ユーザの API キーを指定します
(例)
# Usage: # ruby ./uploader.rb http://hoge.com/api/v1/message.json hoge.jpg # require 'rest-client' url = ARGV.shift files = ARGV RestClient.log = 'stdout' data = {} data["api_key"] = "(API Key)" data["room_id"] = "(Room ID)" data["message"] = "message" files.each do |file| data["files[#{file}]"] = File.new(file, 'rb') end RestClient.post(url, data)
- URL: /api/v1/message.format
発言の更新
- URL: /api/v1/message/id.format
- id (必須) … 更新対象の発言の ID を指定します。自分の発言のみが指定できます
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: PUT
- パラメータ:
- message (必須) … 更新後の発言内容の文字列を指定します
- api_key (必須) … ユーザの API キーを指定します
- URL: /api/v1/message/id.format
発言の削除
- URL: /api/v1/message/id.format
- id (必須) … 削除対象の発言の ID を指定します。自分の発言のみが指定できます
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: DELETE
- パラメータ:
- api_key (必須) … ユーザの API キーを指定します
- URL: /api/v1/message/id.format
部屋の発言の取得
- URL: /api/v1/message/list.format
- room_id (必須) … 部屋の ID を指定します。
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: GET
- パラメータ:
- until_id (任意) … 発言を取得する基準となる ID を指定します。 この ID よりも以前の発言が取得されます。指定しなければ最新の発言を取得します。 older_than と同時には指定できません。
- older_than (任意) … 発言を取得する基準となる ID を指定します。 この ID よりも古い発言が取得されます。指定しなければ最新の発言を取得します。 until_id と同時には指定できません。
- since_id (任意) … 発言を取得する基準となる ID を指定します。 この ID より以降の発言が取得されます。指定しなければ最新の発言を取得します。 newer_than と同時には指定できません。
- newer_than (任意) … 発言を取得する基準となる ID を指定します。 この ID よりも新しい発言が取得されます。指定しなければ最新の発言を取得します。 since_id と同時には指定できません。
- order (任意) … メッセージのソート順序を指定します。 asc を指定した場合には作成日時の昇順、 desc を指定した場合には作成日時の降順になります。
- count (任意) … 取得する発言の個数を指定します。指定しなければ、20個の発言を取得します。
- api_key (private room の場合必須) … ユーザの API キーを指定します。
- URL: /api/v1/message/list.format
部屋の操作 API¶
- 部屋の一覧を取得
- URL: /api/v1/room/list.format
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: GET
- パラメータ:
- api_key (任意) … 指定した場合、 private room も含めて一覧します。
- URL: /api/v1/room/list.format
- 部屋の作成
- URL: /api/v1/room.format
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: POST
- パラメータ:
- name (必須) … 作成する部屋の名前を指定します
- api_key (必須) … ユーザの API キーを指定します
- URL: /api/v1/room.format
- 部屋の更新
- URL: /api/v1/room/id.format
- id (必須) … 名称を変更する部屋の ID またはニックネームを指定します
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: PUT
- パラメータ:
- name (必須) … 変更後の部屋の名前を指定します
- api_key (必須) … ユーザの API キーを指定します
- URL: /api/v1/room/id.format
- 部屋の削除
- URL: /api/v1/room/id.format
- id (必須) … 削除する部屋の ID またはニックネームを指定します
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: DELETE
- パラメータ:
- api_key (必須) … ユーザの API キーを指定します
- URL: /api/v1/room/id.format
- private room へのメンバの追加
- URL: /api/v1/room/add_member.format
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: POST
- パラメータ:
- id (必須) … メンバを追加する部屋の ID またはニックネームを指定します
- api_key (必須) … ユーザの API キーを指定します
- user_id (必須) … 追加するユーザのIDを指定します。
- URL: /api/v1/room/add_member.format
ユーザの操作 API¶
- ログインユーザ情報の取得
- URL: /api/v1/user.format
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: GET
- パラメータ:
- api_key (必須) … ユーザの API キーを指定します
- URL: /api/v1/user.format
AsakusaSatelliteの操作 API (0.8.1以降)¶
- 設定情報の取得。 現在は WebSocketサーバの変更 に関する設定のみが取得できます。
- URL: /api/v1/service/info.format
- format (必須) … 指定した形式で結果を返します。現在は json のみが有効です。
- メソッド: GET
- パラメータ: なし
- URL: /api/v1/service/info.format
bot の作成例¶
以下は、部屋番号と発言をコマンドラインオプションで指定して 発言を行うプログラムの例です。
#! /user/bin/env ruby
# -*- mode:ruby; coding:utf-8 -*-
# ------------------------------
# example for bot
# ------------------------------
# Get from http://$AS_ROOT/account/index
ApiKey = "YOUR_API_KEY"
# EntryPoint
EntryPoint = "http://localhost:3000/api/v1"
# ------------------------------
require 'net/http'
if ARGV.size != 2 then
puts "#{$0} <room_id> <message>"
exit 0
end
room_id, message = *ARGV
uri = URI(EntryPoint)
Net::HTTP.start(uri.host, uri.port) do| http |
# post message
p http.post(uri.path + "/message.json",
"room_id=#{room_id}&message=#{message}&api_key=#{ApiKey}")
end
更新履歴¶
v0.9.0(2014-01-22)¶
- 機能追加: Ruby 2.0 / 2.1 を正式サポート #35 #47 #102 #163 #164
- 機能追加: 絵文字のサジェスト機能を追加 #135
- 機能追加: message/list API に order パラメータを追加 #110
- 機能追加: message/list API に older_than と newer_than パラメータを追加 #162
- 機能追加: 部屋へのユーザの招待で一度に複数ユーザを指定できる機能を追加 #45 #48
- 機能追加: 未ログインのユーザを招待できる機能を追加 #50
- 機能追加: :in_chatroom_controller フックポイントを追加 #70
- 機能追加: WebSocket で送信される JSON データに prev_id フィールドを追加 #112
- 機能追加: QuoteIt プラグインで QuoteIt の URL を指定する環境変数を追加 #120
- 機能追加: API で添付ファイルを追加できる機能を追加 #129
- 機能追加: ブラウザの戻るで戻った際に WebSocket で受信したメッセージが消えないようにする機能を追加 #142
- 機能変更: Twitter API を v1.1 に移行 #62
- 機能変更: Rails のバージョンを 3.1.14 に変更 #132
- 機能変更: いくつかのファイル名を Rails の規約に合わせて変更 #40 #52
- 機能変更: 絵文字を AsakusaSatellite 自身がホストするように変更 #113
- 機能変更: message/list API で HTML メッセージがキャッシュされるように変更 #150
- 機能修正: 存在しない絵文字は絵文字展開をしないように修正 #75
- 機能修正: WebSocket が接続できていない環境でも動作するように修正 #87 #98 #155
- 機能修正: サブディレクトリで動作させた場合に添付ファイルが添付できない不具合を修正 #90
- 機能修正: デスクトップ通知を Firefox 22 以降で動作するように修正 #118
- 機能修正: Safari 7 で添付ファイルが添付できない不具合を修正 #151
v0.8.1(2013-03-24)¶
- 機能追加: 検索結果ページのページネーションを追加
- 機能追加: Aboutページにバージョン表示を追加
- 機能追加: 部屋にニックネームを設定できる機能を追加
- 機能追加: デスクトップ通知の表示時間設定を追加
- 機能追加: Watageプラグイン追加
- 機能追加: Javascript/CSS追加プラグインを追加
- 機能追加: 非公開の部屋操作用のAPI追加
- 機能追加: ビューフックの追加: 個人設定ページ(account_setting_item), Aboutページ(global_setting_item), 全画面の上部・下部(global_header, global_footer)
- 機能追加: UserScript用支援を追加
- 機能追加: プラグイン内のassets/ ディレクトリへのルーティングを追加
- 機能追加: JRuby対応
- 機能追加: AsakusaSatellite本体の操作API追加
- 機能変更: Rails 3.2.11 を利用するように変更
- 機能変更: 添付したファイル名も検索対象に変更
- 機能変更: 認証系を OmniAuth を利用するように変更
- 機能変更: Gemfileから不要な依存ライブラリを削除
- 機能変更: 検索結果の”read more”ボタンのクリック可能領域を拡大
- 機能変更: 検索結果の並び順を時刻の降順に変更
- 機能変更: 添付ファイルの上限サイズを設定できるように変更
- 機能修正: ジェネレートしたプラグインの spec_helper のパスが間違っていたのを修正
- 機能修正: Redmine のチケットの作成時に & や ; が含まれていた場合に文字列が途切れていた問題を修正
- 機能修正: 改行を含むコードをシンタックスハイライトさせると改行に置換されていた不具合を修正
- 機能修正: メッセージの表示ページで、prev に 0 を設定すると全件表示しようとする不具合を修正
- 機能修正: デスクトップ通知に添付ファイル名が表示されるように修正
- 機能修正: メッセージが0件の部屋を開くとJavascriptエラーが発生する不具合を修正
- 機能修正: Redmine認証プラグインで末尾が/のURLを設定するとエラーになる不具合を修正
- 機能修正: 未ログイン状態でファイルをD&DするとJavascriptエラーが発生する不具合を修正
- 機能修正: 未ログイン状態で部屋の設定画面を開くと 404 が出る不具合を修正
- 機能修正: ビューフックジェネレータの生成するコードに、存在しないメソッドのテストが含まれていた不具合を修正
- その他細かな修正
v0.8.0(2012-10-13)¶
- 機能追加: Ruby 1.9 に対応
- 機能追加: New Relic を利用するように変更
- 機能追加: 絵文字を利用できるフィルタ (as_emoji_filter) を追加
- 機能追加: robots.txt を記述
- 機能変更: Rails 3.2.8 を利用するように変更
- 機能変更: Assets Pipeline を利用するように変更
- 機能変更: Development/Test 環境で Nokogiri を利用しないように変更
- 機能変更: いくつかの設定を環境変数を利用するように変更
- 機能変更: iPhone ビューで Send ボタンを非表示に変更
- 機能変更: 音声ファイルのフォーマットを mp3 から ogg に変更
- 機能修正: タイムゾーンが JST 決め打ちだったのを修正
- 機能修正: Redmine の URL が / で終わらない場合に正しく動作しない問題を修正
- 機能修正: v0.7.2 で 2.0.0 より古い MongoDB 動作しなくなっていた問題を修正
- 機能修正: サブディレクトリにデプロイした場合に、添付ファイルが動作しない問題を修正
- 機能修正: フィルタが例外を投げた場合に例外がキャッチされない問題を修正
- 機能修正: QuoteIt フィルタが引用を失敗した場合に表示が崩れる問題を修正
- その他細かな修正
v0.7.2(2012-08-05)¶
- 機能追加: OS X 10.8 の通知センターに対応
- 機能追加: travis-ci.org 自動ビルドに対応
- 機能修正: Firefox / Opera / IE でマウスオーバーで表示が崩れる問題を修正
- 機能修正: ダブルクォートを含む URL を QuoteIt プラグインで展開できない問題を修正
- 機能修正: v.0.7 以降で動作していなかった RSS リンクを削除
- 機能修正: v.0.7 以降で api/v1/message/list がパラメータを処理できない不具合を修正
- 機能修正: v.0.7 以降で検索結果のメッセージの順序が不定だった問題を修正
- 機能修正: v.0.7.1 以降でメッセージを開いた時に対象メッセージがハイライトされない問題を修正
- 機能修正: Pusher の JavaScript を http から https に変更
v0.7.1(2012-05-26)¶
- 機能修正: 不要なファイルの削除
- 機能修正: 不要なコードの削除
- 機能修正: IE で画像の border が表示されてしまうのを修正
- 機能修正: local_auth プラグインが v.0.7 で動作していなかったのを修正
- 機能修正: Copyright を 2011-2012 に変更
- 機能修正: Gemfile の内容を整理
v0.7(2012-01-04)¶
- 機能追加: WebSocketサーバを設定可能に
- 機能追加: QuoteItプラグイン追加
- 機能追加: RedmineAuthプラグイン追加
- 機能追加: 自動テストを guard + spork ベースに変更
- 機能追加: Rails 3.1に対応。
- 機能修正: フィルタプラグインの競合を防ぐため、処理対象をテキストからDOMに変更
v0.6(欠番)¶
v0.5(内部リリースのみ)¶
- 機能追加: 非公開の部屋作成を追加
- 機能追加: 使用DBをMongoDBへと変更
- 機能追加: herokuでの動作に対応
- 機能修正: コードハイライト時のフォントを等幅フォントに修正
- 機能修正: 部屋ごとに検索フォームを追加
- 機能修正: メッセージの編集後、OKボタンを非アクティブにするように修正
- 不具合修正: メッセージがひとつもない部屋で readmore を押すとエラーがでる不具合を修正
v0.4(欠番)¶
v0.3.0(2011-04-01)¶
- 機能追加: マニュアル作成
- 機能追加: Firefox/Safari/Operaのサポートを追加 (参照: 対応ブラウザ )
- 機能追加: Ubuntu/Windowsのサポートを追加
- 機能追加: APIを追加 (参照: API )
- 機能追加: Graphvizプラグインを追加 (参照: コードハイライト )
- 機能追加: 部屋ごとの設定ページを追加(参照: 部屋の設定変更)
- 機能追加: プラグインごとの設定ページを追加(参照: 部屋の設定変更)
- 機能追加: 認証機能のプラグイン化(参照: QuoteItプラグイン)
- 機能追加: MITライセンスであることを明示
- 機能修正: Rails本体とWebsokectサーバの通信方法をHttpからMessagePack-RPCに変更
- 機能修正: 発言通知時に部屋名を一緒に出すように修正
- 機能修正: 部屋の改名・削除をログインユーザ全員ができるように修正
- 機能修正: 部屋名をタイトルに含めるように修正
- 機能修正: 存在しない部屋をURLで直接指定した場合、404エラーを出すように修正
- 機能修正: ブラウザ終了後もログイン状態を保持するように修正
- 機能修正: Windows版のGoogle Chromeでアイコンがずれる不具合を修正
- 機能修正: APIから他人の発言を削除できる不具合を修正
- 機能修正: Rails 3.1で廃止される機能を使わないようにコードを修正
- 機能修正: read moreで他の部屋のメッセージがとれてしまう不具合を修正
- 機能修正: メッセージの個別ベーシ(<AS_ROOT>/message?id=xxx)で他の部屋のメッセージが表示される不具合を修正
- 機能修正: codefirst.org上の画像を参照したいた不具合を修正
- 機能修正: 発言のないページでJavascriptエラーがでる不具合を修正
- 機能修正: 削除した部屋をURLで直接指定すると表示できてしまう不具合を修正