ウィジェットを用いたSuperSaaSとの連携
伴い、SuperSaaS日本語版サイトでもウィジェットエディタページが新設されましたが、翻訳が間に合っていない箇所や機械翻訳そのままの箇所など散見され、現状ではかなりわかりにくい不安定な状態に感じられますので、このページではオリジナルの英語版サイトに準拠した内容としています。
SuperSaaS公式サイトでは、構築した予約システムと連携できるウェブサイトに埋め込むウィジェットを簡単に生成できるウィジェットエディタが公開されています。
ウィジェットエディタを用いると、誰でも簡単にホームページにSuperSaaS予約システムと連携するボタンや、埋め込みができるウィジェットが作れます。
ウィジェットエディタは公式サイトで公開されています。
SuperSaaS管理メニューの環境設定連携の予約ボタンからもリンクして遷移できます。
SuperSaaSウィジェットエディタ
SuperSaaSのウィジェットエディタはオンラインで動的に生成することができます。
ウィジェットを生成するためには、ウィジェットエディタページでSuperSaaSにログインしておく必要があります。
ページにログインの案内がありますのでloginをクリックしてログインすることで利用できます。
同じブラウザの別タブなどでログインした状態でも、自分の予約システムと連携したウィジェットを生成するために、このページで改めてログインする必要があるようです。
ウィジェットエディタページには画面右側にプレビュー機能が付いていますので、どのようなウィジェットになるかを動的に画面上で確認しながら作成することができます。
サイトページがレスポンシブな設計なので、プレビューは画面が狭いと右側でなく設定の下側に位置が移動します。
使い勝手を考えると、横に広めの画面で用いたほうが良いかもしれません。
ウィジェットの種類
SuperSaaSウィジェットの種類として、Buttonと、Frameの二種類から選択できます。
- Button
- クリックすることで対象となる予約システム画面をポップアップで表示する、ボタン型ウィジェットです。
- Frame
- 直接ウェブページに対象となる予約システム画面を埋め込む、フレーム型のウィジェットです。
ボタン型はクリックが必要となるワンクッションがありますが、ただのボタンなので埋め込むページの見た目や構成といったデザインに影響しにくいです。
フレーム型は直接予約システムをページに埋め込みますので、ページの構成や見た目に影響が大きいですが訴求力が強いです。
Customize button style（ボタン型のウィジェット専用の追加設定）
ウィジェットの種類でボタンを選択した場合にのみ、ボタン型専用の設定が追加されます。
フレーム型の場合は必要ない設定なので表示されません。
ボタン型の場合、設定の上にも独自のプレビューが表示されます。
ただし、このプレビューは見た目だけのプレビューのようでクリックしても反応しません。
Button label
ボタンに表示したい文字列を選択できます。
一番下の入力枠の選択肢は、その入力枠で設定した自由な文言をボタンに表示できます。
Button size and radius
ボタンの大きさや角の丸みをスライダーで調整できます。
- Size
- ボタンの大きさを調節できます。
大きさといっても、button要素のstyleのpaddingの値調整となっていますので、ボタンの文字と外周までの余白の調整です。 - Radius
- ボタンの角の丸みを調節できます。
button要素のstyleのborder-radiusの値調整です。
Label font, color and size
ボタンに表示される文字列に対する装飾を設定できます。
- Font
- 表示用のフォンを選択できます。
button要素のstyleのfont-familyの値調整です。 - Text Color
- 表示する文字の色身を調節できます。
button要素のstyleのcolorの値調整ですが、スライダー一つでの調節のためか、rgbが等しく調整されてグレースケール的な調節になっているようです。 - Text Size
- 表示する文字の大きさを調節できます。
button要素のstyleのfont-sizeの値調整です。 - Bold text?
- チェックを入れることで表示する文字を強調装飾することができます。
button要素のstyleのfont-weightの値選択です。
Button color
ボタンの背景色を指定できます。
カラーマップからの視覚的な指定が可能です。
button要素のstyleのbackground-colorの指定です。
これらの設定は、button要素の設定をビジュアル的にしたものです。
独自の値にしたり、追加の設定を行いたい場合は生成されるコードのbutton要素を直接編集することも可能です。
Choose widget type
表示するウィジェットの形式を指定できます。
4種類があり、全てのスケジュールタイプで利用可能な「Calendar Month」、「List」と、定員制タイプでのみ選択できる「Cards」、リソースタイプとサービスタイプで選択できる「Buttons」から選択できます。
Choose a Button or a Frame
ウィジェットの表示領域（大きさ）を指定できます。
「Width（横）」と「Height（縦）」で設定できます。
ウィジェット構成要素のwidthとheightの値となりますので、「px」や「％」、「vh」などでの指定が可能です。
Heightに「px」以外の相対的や動的となる設定はHTML構文的な壁がありますので、「px」での指定が無難です。
実運用時にはレスポンシブ対応など、生成されたコードのカスタマイズや、JSによる動的な追加調整など検討する必要があるかもしれません。
Customize widget
表示されるウィジェットのオプション設定です。
- Menu
- SuperSaaSのメニューバーの表示可否を指定できます。
Hideで非表示、Showで常駐表示と思われます。 
Hideにすると非表示なのですが、ログインしていると表示されるようです。
あくまでログインしていないときの状態の設定となるようです？- Menu position
- SuperSaaSのメニューバー位置を指定できます。
Topはウィジェット上部に。Bottomはウィジェット下部にメニューバーを配置します。 - Unavailable
- ボタン形式の場合の設定で、タイル状に並べられた時間帯別の予約ボタンのうち、予約できない時間帯のボタンに対する装飾を指定できます。
Dim (gray out)は非活性状態で表示します。
Hideは予約不可能なボタンを非表示にしますが、ボタンをタイリングした時に詰めて表示しないで歯抜け状態にして表示します。
Collapseは非表示にしたうえで、ボタンをタイリングした時に詰めて表示します。 
- Service selector
- 対象となるスケジュールがサービスタイプで、複数のサービスが登録されていて最初にサービスを選択する設定になっている場合の設定です。
Service listは登録サービスをリスト表示して選択を促します。Dropdownはサービスをドロップダウン形式で選択を促します。 - Button label
- 上のService selectorでService listが選択されいる場合の設定です。
リスト表示されるサービスの選択ボタンに表示される文字列を指定できます。 - Hide schedule title
- チェックを入れることでスケジュールタイトルの表示を非表示にできます。
- Auto-select first available date
- チェックを入れることで直近で予約可能な日付のスケジュールで表示します。
チェックがない場合は予約可能の可否にかかわらず現在の日付でスケジュールが表示されます。 - Hide finish time
- チェックを入れることで予約開始時間のみの表示として、予約の終了時間を非表示にできます。
- Hide slot titles
- 定員制タイプに対するウィジェットのみの設定です。
予約対象となるスロットのタイトルを非表示にできます。 - Hide level pie chart icon
- 定員制タイプに対するウィジェットのみの設定です。
何かのアイコンを非表示にできるようですが、レベル円グラフが何を指すのかわかりませんでした。 チェックをオンオフしながらいろいろいじってみましたが、どこが変化しか気づけませんでしたので、何かしら条件があるのかと思います…
また何かわかったら追記して更新しますね。- Show a list of schedules first
- チェックを入れることで、ウィジェット作成時にどのスケジュールを選択していようとも、スケジュールリスト（スケジュールの選択）表示となります。
- アクセスコントロールのルートURLにアクセスされた時の挙動設定でスケジュールをリストで表示を選択している場合のみの選択肢です。
未実装オプション群
まだ検討中のようですが、いくつか未実装の設定が見え隠れしていました。
- Colors
- 何かしら色の指定ができる設定？
- Hide
- 定員制タイプの設定のようで、満員のスロットを非表示にする設定？
- Access
- 予約対象の詳細へのリンクを付与する設定？
Code snippet to put on your site
設定に合わせてリアルタイムにウィジェットコード（javascript）が動的に生成されます。
タイトル横の
Copyアイコンをクリックすることで、クリップボードにウィジェット生成用のソースコードをコピーできます。
ウィジェットコードは、ホームページなどに張り付けてすぐにでも利用が可能です。
ウィジェットからのアクセスを無効化したい場合
SuperSaaSでスケジュールを構築時のデフォルトは、ウィジェットからのアクセスを許可している状態です。
もし、ウィジェットからのアクセスを無効化したい場合は、対象スケジュールの設定レイアウトで有効／無効の切り替えを設定することができます。
どの表示形式でご利用されますかの別サイトのウィジェットとしての統合を許可するのチェックを外すことで、ウィジェットからのアクセスをブロックすることができます。
ユーザーAPIを用いたSuperSaaSウィジェット活用
ユーザーAPIの一部がウィジェットでも利用可能となり、ウィジェットの表示時に既存のユーザーとしてログインした状態にしたり、新規ユーザー登録、あるいは更新をしてから表示などが可能です。
ユーザーAPIは認証用のチェックサムがMID5ハッシュ化されたユーザー別の認証用文字列なんですよね……ちょっとめんどくさい。。。
管理者用の統括されたAPIキーが使えないのは、各ユーザーごとにセキュリティを持たせているということでしょうかね
指定した既存ユーザーでログインした状態でウィジェットを表示する
supersaas_api_userにユーザーネームを、supersaas_api_checksumにチェックサムの値を指定してウィジェットを表示するためのJavascriptコードの前に、同じくJavascriptで記載するだけで、ウィジェット表示時に指定ユーザーとしてログインした状態にできます。
| 定義名 | 概要 |
|---|---|
| supersaas_api_user | ログイン状態にしたい既存のユーザー名を指定します |
| supersaas_api_checksum | 対象ユーザー用のMD5ハッシュ化された認証キーを指定します |
例：
<script>
var supersaas_api_user = {“name”:”ログインしたいユーザーネーム“};
var supersaas_api_checksum = “対象ユーザー用のMD5ハッシュ化されたチェックサム“;
</script>
↓ウィジェット表示コード↓
<script src=”https://cdn.supersaas.net/widget.js”></script>
<script class=”supersaas-widget”>ウィジェット表示用のコード</script>
新規ユーザー登録あるいは、更新してログインした状態でウィジェットを表示する
ウィジェットを表示するためのJavascriptコードの前に、同じくJavascriptで新規ユーザーを構成するユーザー情報を記載します。
supersaas_api_user_idには末尾に「fk」を付与する外部キーID（任意の数値）で指定します。
外部キーIDの既存ユーザー情報があればそのユーザー情報を上書き更新し、存在しない外部キーIDであれば新規ユーザーとしてユーザー情報が追加されます。
supersaas_api_userにはユーザー情報を。supersaas_api_checksumにはユーザー登録に必要なMD5ハッシュ化されたキー文字列を指定します。
| （物理名） 論理名 | 概要 |
|---|---|
| supersaas_api_user_id | ユーザー固有の一意な管理用IDです SuperSaaSの管理ユーザーIDとは異なる外部キーIDです 末尾に「fk」を付与して指定します |
| supersaas_api_user | ユーザー情報の内容です 構成はアクセスコントロールで指定されているユーザー情報の構成に準拠します JSON形式で指定します |
| supersaas_api_checksum | 対象ユーザー用のMD5ハッシュ化された認証キーを指定します |
例：
<script>
var supersaas_api_user_id = “外部キーIDfk”;
var supersaas_api_user = {“name”:”ユーザー名”,”full_name”:”フルネーム”,”phone”:”電話番号”,”address”:”住所”など必要なユーザー情報};
var supersaas_api_checksum = “対象ユーザー用のMD5ハッシュ化されたチェックサム“;
</script>
<script src=”https://cdn.supersaas.net/widget.js”></script>
<script class=”supersaas-widget”>var supersaas = new SuperSaaS(“174981:SSS-FAN”,”396461:chk_r000″,{“widget_type”:”frame”})</script>
SuperSaaSのウィジェットは産声を上げたばかり
ウィジェットエディタはようやくベータ版表記が外れ正式化したばかりです、公式からの詳細な機能紹介はなく、新機能としてのアピールが散見される程度です。
現時点での活用はいろいろと模索が必要かもしれません。
キモはwidget.jsですし、いろいろ活用の検討ができるかも。
ただ、ポップアップJavascriptにしろ、Ifreamにしろ、レスポンシブな対応設計や、複数のウィジェットを埋め込んだりなどの競合、キャッシュやセッションなどの不測の諸問題など、公式サポートを活用しながら十分な動作確認をもって実装としたいですね！