WOFF (WORKS Front-end Framework)

WOFF とは {#about-woff}

WOFF (WORKS Front-end Framework) は、LINE WORKS が提供する Web アプリのプラットフォームです。このプラットフォームで動作する Web アプリを「WOFF アプリ」と呼びます。
WOFF アプリの実体は HTML と JavaScript をベースとした Web アプリです。WOFF アプリを実行したユーザーの情報の取得や、WOFF アプリを呼び出したトークルームへのメッセージの送信などができます。

WOFF の特徴 {#why-use-woff}

WOFF を使うことで、さまざまな Web アプリを LINE WORKS アプリ上に載せることができます。LINE WORKS アプリ上で動くミニアプリとして、多彩なサービスを LINE WORKS を通して提供できます。

WOFF を活用するメリットとして以下が挙げられます。

LINE WORKS アプリ上で起動するミニアプリを開発できます
- 業務のためのさまざまなツールを WOFF アプリとして開発・提供することで、ユーザーは LINE WORKS アプリの一部のような体験でシームレスに利用できるようになります。
- これによって、さまざまな業務情報を LINE WORKS アプリ上に集約させ、利便性向上に繋げることができます。
WOFF SDK で LINE WORKS の機能やユーザー情報を利用できます
- WOFF SDK を通して、ユーザー情報の取得やメッセージ送信などの機能を利用できます。
自由度の高い UI を作成できます
- WOFF アプリは Web ベースのアプリケーションなので、Web アプリと同様の方式で開発します。
- そのため Web の技術を用いて自由に UI を実装することができます。

Bot との違い {#compare-with-bot}

Bot と WOFF はどちらも LINE WORKS との連携アプリを開発できる機能ですが、それぞれ以下のような違いがあります。

	Bot	WOFF
特徴	チャットボット機能として、トークルーム上でやりとりする会話形式の UI を提供します。ユーザーと会話するの同じような体験で利用できることが特徴です。	LINE WORKS 上で動く Web アプリとして自由度の高い UI を設計可能です。
表示	Bot が対応しているさまざまなメッセージタイプを使い分けて、トークで情報を表示します。	Web ベースに自由なレイアウトで情報を表示します。
入力	基本、一問一答です。テキスト・スタンプ・画像などのトーク送信や、Flex Message やリッチメニュー、クイックリプライを使ったアクションによって入力します。	Web 技術を用いてさまざまな方法を実装可能です (ボタンやフォーム入力を使って複数項目の一括入力など)。
アクセス	Bot とのトークルームを開きます。	WOFF URL から開きます。
その他	メッセージ送信でプッシュ通知が可能。	-
使い所	会話形式にやりとりするもの。 FAQ チャットボットや、簡易な入力のみで十分な場合。	複雑な入力やグラフィカルな表示を必要とする場合。

それぞれ特徴を踏まえて両者を使い分けて、適したユーザー体験を設計してください。

参考
Bot と組み合わせて利用するも参照ください。

用語 {#glossary}

項目	説明
WOFF ID	WOFF アプリの識別子で、WOFF アプリを登録する際に発行されます。 WOFF SDK の初期化関数 woff.init() で使用します。
WOFF URL	WOFF アプリを実行する際にアクセスする URL で、WOFF ID が含まれています。
Endpoint URL	WOFF アプリが配置されている URL です。 WOFF URL にアクセスすると Endpoint URL にリダイレクトされます。
WOFF ブラウザ	WOFF アプリが実行される専用ブラウザです。モバイルアプリで WOFF URL を開くと、WOFF ブラウザが起動します。
Access Token	woff.init() が実行されたときに WOFF SDK が発行するトークンです。発行後 12 時間が経過する、もしくはユーザーが WOFF アプリを閉じるとトークンは無効になります。

WOFF アプリが動く環境と推奨環境 {#operating-environment}

WOFF アプリをモバイル版の LINE WORKS 上で開いた場合は WOFF ブラウザで立ち上がり、その他の環境で開いた場合は外部ブラウザで立ち上がります。

環境	LINE WORKS 推奨環境
iOS 版 LINE WORKS	最新バージョン。 WOFF ブラウザで開きます。WOFF ブラウザには WKWebView が使用されます。
Android 版 LINE WORKS	最新バージョン。 WOFF ブラウザで開きます。WOFF ブラウザには Android WebView が使用されます。
PC 版 LINE WORKS	最新バージョン。外部ブラウザで開きます。
ブラウザ版 LINE WORKS	最新バージョン。外部ブラウザで開きます。

注意
LINE WORKS アプリは最新バージョンの環境での利用を推奨します。
各 OS 環境や外部ブラウザ環境は LINE WORKS のシステム要件に従います。
外部ブラウザで開いた場合は、使用できる機能に一部制限があります。詳しくは、API リファレンスを参照してください。

WOFF アプリの登録 {#create-woff-app}

1. WOFF アプリを登録する {#settings}

WOFF アプリは Developer Console の API > ClientApp > WOFFアプリ から登録します。「登録」ボタンから登録します。

項目	説明
WOFF 名	WOFF アプリの名前です。本項目で指定した WOFF アプリ名は、ユーザーに表示されます。最大文字数： 20 文字
Endpoint URL	WOFF アプリを実装した Web アプリのURL (例：`https://example.com/my-app/?key=value` ) です。 WOFF アプリを起動した際に、この URL のコンテンツが利用されます。最大文字数： 500 文字 https の URL を登録する必要があります。 URL フラグメント (#URL-fragment) は指定できません。
サイズ	WOFF アプリの画面サイズです。次のサイズから選択してください。 Full Tall Compact
Scan QR	woff.scanQR() を利用する場合は ON にしてください。
WOFF URLリダイレクト検証	WOFF URLリダイレクト検証を利用する場合は ON にしてください。 ON に設定する場合には、Secret Keyを指定します。

また、利用する機能によって Scope を設定する必要があります。WOFF SDK を参照してください。

注意
woff.getAccessToken() で取得した Access Token には、WOFF アプリを登録した Developer Console アプリで選択されているすべての Scope が含まれます。選択される Scope は最小になるよう設定してください。

ひとつの Developer Console アプリには、最大で 30 個の WOFF アプリを登録できます。

WOFF アプリを登録すると、Endpoint URL に紐づいた専用の WOFF ID および WOFF URL が作成されます。

項目	説明
WOFF ID	WOFF アプリの識別子。WOFF SDK の初期化関数 woff.init() で使用します。例. `1654426689BR7LN87b`
WOFF URL	WOFF アプリを実行する際にアクセスする URL。WOFF ID が含まれています。例. `https://woff.worksmobile.com/woff/1654426689BR7LN87b`

2. WOFF アプリを開く {#open-woff-app}

WOFF URL にアクセスすることで、WOFF アプリが開きます。

WOFF URL にアクセスします。
WOFF ブラウザが立ち上がり、紐づいた Endpoint URL にリダイレクトされWOFF アプリが開きます。
- ※ PC 版やブラウザ版の LINE WOKRS から開いた場合は外部ブラウザで開きます。

また、WOFF URL に追加情報 (path や Query Parameter) を付与してアクセスした場合、Endpoint URL に追加情報が付与された状態でリダイレクトされます。

ユーザーがアクセスする URL	リダイレクト先URL
WOFF URL 例. `https://woff.worksmobile.com/woff/1654426689BR7LN87b`	Developer Console にて設定した Endpoint URL 例. `https://example.com/my-app/?key=value`
追加情報を含む WOFF URL 例. `https://woff.worksmobile.com/woff/1654426689BR7LN87b/path_A/?key1=value1`	Developer Console にて設定した Endpoint URL に追加情報が付与された URL 例. `https://example.com/my-app/path_A/?key=value&key1=value1`

注意
Query Parameter を指定する場合には、"?" の前に "/" が必要です。
URI フラグメント "#" は使用できません。
モバイルアプリで WOFF を利用する場合、外部ブラウザ設定が有効化されていても LINE WORKS 内で WOFF アプリが立ち上がります。
また、WOFF アプリ内から他のページを開きたい場合は SDK の woff.openWindow() をご利用ください。

WOFF アプリの開発 {#develop-woff-app}

サンプルコード {#sample-code}

WOFF アプリのサンプルコードを公開しています。

詳しくはサンプルコードを参照ください。

WOFF アプリのタイトル {#title-of-woff-app}

WOFF アプリが表示される際のタイトルバーに表示される文字列を、Web アプリの HTML ソースの title 要素に指定します。

<!DOCTYPE html><html lang="en">  <head>    <title>WOFF App</title>...

WOFF SDKの指定 {#import-woff-sdk}

WOFF アプリでは、WOFF SDK を利用して、WOFF アプリを実行したユーザーの情報の取得や、アプリが呼び出されたトークルームへのメッセージの送付などができます。 WOFF SDK を使用するには、WOFF アプリの HTML ソースの script 要素の属性に WOFF SDK の URL を指定します。

<script charset="utf-8" src="https://static.worksmobile.net/static/wm/woff/edge/3.7.1/sdk.js"> </script>

現在の WOFF SDK の最新バージョンは 3.7.1 です。UTF-8 で作成されています。

WOFF SDK の詳細に関しては WOFF SDK を参照ください。

外部ブラウザでユーザー情報を取得する {#external-userinfo}

ユーザー情報を取得する WOFF アプリを外部ブラウザで利用する場合、別途ログイン操作が必要です。
woff.init() 後に woff.login() を呼びだしログイン処理を行なってください。
既にブラウザ上にログインセッションがある場合は、ログイン画面はスキップされます。

詳しくは woff.login() を参照ください。

WOFF URLリダイレクト検証 {#woff-redirect-verification}

WOFF Endpoint URL へのアクセスが、WOFF URL を経由したリダイレクトであるか検証できます。 WOFF の Endpoint URL の先となる Web サーバー側にて検証してください。

設定方法

WOFF アプリを登録・修正する際に、WOFF リダイレクト検証設定を有効にし、Secret Key を入力します。
Secret Key は Signature の生成・検証に使用する任意の値で、80 字以内の半角英数字および一部の記号（例：! @ & ( ) - _ + [ ] { } , .）で指定します。

署名検証

WOFF リダイレクト検証設定が有効な場合、WOFF URL から WOFF Endpoint URL へのリダイレクト時に、timestamp 、 nonce 、signature がクエリパラメータとして付与されます。
signature は、Secret Key を秘密鍵とし、woffId 、timestamp 、nonce を結合した文字列を HMAC-SHA256 アルゴリズムで署名したものです。

Parameter	Description
timestamp	ユーザーが WOFF URL にアクセスした時刻 (UNIX 時間)
nonce	Replay Attack 防止のために WOFF Server が付与する任意の値
signature	生成された Signature

WOFF URL を経由したリダイレクトであるか検証するには、Secret Key を秘密鍵として woffId 、timestamp 、nonce を結合した文字列 {woffId}{timestamp}{nonce} を HMAC-SHA256 アルゴリズムで署名して Base64 URL エンコードし、それとパラメータとして渡された signature の値とを比較してください。

Java での実装例は以下のとおりです。

    import javax.crypto.Mac;    import javax.crypto.spec.SecretKeySpec;    import java.util.Base64;    // get timestamp, nonce, and signature from query parameter    // get woffId and secretKey from WOFF setting page    String data = WoffId + timestamp + nonce;    Mac mac = Mac.getInstance("HmacSHA256");    mac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"));    byte[] hmacBytes = mac.doFinal(data.getBytes("UTF-8"));    String expected = Base64.getUrlEncoder().withoutPadding().encodeToString(hmacBytes);    // compare expected and signature

Python での実装例は以下のとおりです。

    import hmac    import hashlib    import base64    # get timestamp, nonce, signature from query parameter    # get woffId and secretKey from WOFF Setting page    data = f"{woffid}{timestamp}{nonce}"    hmac_bytes = hmac.new(        secretkey.encode('utf-8'),        data.encode('utf-8'),        hashlib.sha256    ).digest()    expected = base64.urlsafe_b64encode(hmac_bytes).decode('utf-8').rstrip('=')    # compare expected and signature

注意
Bot の callback の署名検証と同様の仕組みですが、WOFF リダイレクト検証では署名をURLのクエリパラメータを通して受け取る関係で、Base64 エンコードではなく、Base64 URL エンコード を使用します。同じコードを使いまわせないことをご注意ください。

開発ガイドライン

WOFF アプリを開発する際は、開発ガイドラインに従ってください。