WOFF SDK

WOFF SDK を使用するには {#how-to-use-woff-sdk}

WOFF アプリで SDK を使用して WOFF の処理を行う際には、以下の流れで処理を行います。

1. WOFF アプリの初期化
2. WOFF アプリの実行環境の確認
3. WOFF アプリ内での処理を実施

• 例) 新しいウィンドウを表示して、画面を遷移する
• 例) 現在開いているトークルームにメッセージを送る
• 例) アクセストークンを取得して、LINE WORKS API を実行する

4. WOFF アプリを閉じる

WOFF アプリの初期化 {#init-woff-app}

WOFF SDK を使用する際には、最初に woff.init() メソッドを実行します。
woff.init() メソッドは WOFF アプリを初期化し、WOFF アプリで WOFF SDK の他のメソッドを呼び出すことができるようにします。
woff.init() は Endpoint URL に初めてリダイレクトされるときに実行されます。
他のタイミングで実行すると、INIT_FAILED エラーが発生しWOFF アプリを開くことができなくなります。
woff.init() の woffId には Developer Console で WOFF アプリを登録した際に発行された WOFF ID を入力します。

woff  .init({    woffId: "123456-abcedfg" // 発行された WOFF ID を指定する  })  .then(() => {    // WOFF API を実行する  })  .catch((err) => {    // 初期化処理中にエラーが発生した場合    console.log(err.code, err.message);  });

注意事項

• woff.init() は、ページ読み込みが完了した後 (load イベント後) に実行してください。適切に初期化が実行されない場合があります。
• WOFF アプリが実行されると、URL に付与された woff.state や access_token の情報を基に woff.init() が実行されます。初期化を正しく実行するために、フロントエンドの処理が完了する前に URL を変更しないでください。
• WOFF アプリが最初に実行される URL には、woff.state にアクセストークンなどの機密情報が含まれているため、外部ロギングツールに URL 情報を送信しないことをお勧めします。

OIDC ログイン時の scope の指定 {#init-woff-app-oidc-scope}

OIDC では、クライアントは認証リクエストの scope パラメータに openid を含めて明示的に渡す必要があります。WOFF SDK では、woff.init() と woff.login() の scope パラメータで、呼び出し時に OIDC の scope を直接指定できます (WOFF SDK 3.7.4 以降)。

• 外部ブラウザ環境で scope を指定した場合、WOFF SDK はログイン時の認証リクエストにその値をそのまま渡します。
• モバイルアプリ (LINE WORKS アプリ) 環境では、LINE WORKS アプリがトークンを直接渡すため、scope パラメータは無視されます。

scope は次の優先順位で決まります。

1. woff.login({ scope }): 呼び出し時に指定した scope が最も優先されます。
2. woff.init({ scope }): woff.login() で scope を指定しなかった場合に使用されます。
3. 指定なし: woff.login() または woff.init() で scope を指定しない場合、アプリで選択した Scope がそのまま付与されます。ただし、openid Scope が付与されたアプリでは LINE WORKS の認証サーバーがエラーを返すため、woff.login() または woff.init() の scope に openid を含めて指定する必要があります。

参考

• scope には、アプリで選択した Scope の一部だけを指定できます。この場合、アクセストークンには指定した scope だけが付与されるため、WOFF アプリから呼び出す API の Scope (例: user.read) も含める必要があります。
• アプリで選択していない Scope を指定すると、認証リクエストが拒否されます。
• openid を含めた場合のみ、ID トークンが発行されます。発行された ID トークンは woff.getIDToken() と woff.getDecodedIDToken() で取得できます。

WOFF アプリの実行環境の確認 {#get-platform-info}

woff.isInClient() メソッドと woff.getOS() メソッドを呼び出して、WOFF アプリが実行されている環境を取得します。
WOFF アプリから実行されることを前提としている処理を実装する場合は、woff.isInClient() メソッドの結果が true の場合のみに処理するように実装します。

新しいウィンドウを表示して、画面を遷移する {#open-windows}

woff.openWindow() メソッドは、LINE WORKS のアプリ内ブラウザもしくは外部ブラウザで指定された URL を実行します。

現在開いているトークルームにメッセージを送る {#send-message}

woff.sendMessage() メソッドは、ユーザーに代わって WOFF アプリが開かれたトークルームにテキストメッセージを送信します。
次のコードではボタンがクリックされた際に "Hello、Works!" をトークルームに送信します。

document.getElementById('sendMessageButton').addEventListener('click', function(){  if (!woff.isInClient()) {    sendAlertIfNoInClient();  } else {    woff.sendMessage({      'content': 'Hello、Works！'    }).then(function() {      window.alert('Message sent');    }).catch(function(error){      window.alert('Error sending message：' + error);    });  }});

woff.sendFlexMessage()メソッド を使用すると Flexible Template を使用して WOFF アプリが開かれたトークルームにメッセージを送信します。

WOFF アプリを閉じる {#close-woff-app}

woff.closeWindow() メソッドを実行すると、WOFF アプリが終了します。

WOFF SDK API リファレンス {#api-reference}

woff.init() {#woff-init}

WOFF アプリを初期化します。
woff.init() を呼び出した後に、他のメソッドを呼び出すことができます。 初期化が実行される際に、LINE WORKS からアプリを実行したユーザーのアクセストークンを取得できます。

WOFF アプリが初期化される前に実行可能なメソッド

• woff.ready
• woff.getOS()
• woff.getVersion()
• woff.getWorksVersion()

WOFF アプリの初期化の注意事項

• woff.init() は、ページ読み込みが完了した後 (load イベント後) に実行してください。適切に初期化が実行されない場合があります。
• woff.init() は Endpoint URL に初めてリダイレクトされるときに実行されます。他のタイミングで実行すると、INIT_FAILED エラーが発生し WOFF アプリを開くことができなくなります。
• WOFF アプリが実行されると、URL に付与された woff.state や access_token の情報を基に woff.init() が実行されます。初期化を正しく実行するために、フロントエンドの処理が完了する前に URL を変更しないでください。
• WOFF アプリが最初に実行される URL には、woff.state にアクセストークンなどの機密情報が含まれているため、ロギングツールなどの外部に URL 情報を送信しないように注意してください。

Parameters {#woff-init-parameter}

Sample {#woff-init-sample}

// 基本woff.init(  config,  successCallback,  errorCallback)// Promise オブジェクトを使用した方法woff  .init({    woffId: "123456-abcedfg" // 発行された WOFF ID を指定する  })  .then(() => {    // WOFF API を実行する  })  .catch((err) => {    // 初期化処理中にエラーが発生した場合    console.log(err.code, err.message);  });// コールバックを使用する方法woff.init({ woffId: "123456-abcedfg" }, successCallback, errorCallback);// OIDC の scope を指定する方法 (外部ブラウザ環境ではログイン時に渡される)woff  .init({    woffId: "123456-abcedfg",    scope: "openid profile"  })  .then(() => {    // WOFF API を実行する  })  .catch((err) => {    // 初期化処理中にエラーが発生した場合    console.log(err.code, err.message);  });

Return value {#woff-init-response}

Promise オブジェクトを返します。

woff.ready {#woff-ready}

woff.init() を実行して WOFF アプリの初期化が完了した後に実行するアクションを記述します。

woff.ready.then(() => {  // woff.init が完了した後に処理を行う})

woff.init() 実行時にエラーが発生しても WoffError オブジェクトを返しません。また、woff.ready も reject しません。

woff.getChannelId() {#woff-getchannelid}

WOFFアプリが開いているトークルームのチャンネル ID を取得します。

注意

• この API は、モバイルアプリでのみ利用できます。
• トークルーム以外の画面で WOFF アプリが実行されている場合はチャンネル ID を取得できません。
• この API は、WOFF SDK 3.7.1 以降で利用できます。

Parameters {#woff-getchannelid-parameter}

なし

Example {#woff-getchannelid-sample}

woff.getChannelId()

Return value {#woff-getchannelid-response}

Promiseオブジェクトが返されます。

woff.getOS() {#woff-getos}

WOFF アプリを実行する環境を取得します。

Parameters {#woff-getos-parameter}

なし

Sample {#woff-getos-sample}

woff.getOS()

Return value {#woff-getos-response}

WOFF アプリが実行されている環境が文字列として返されます。

woff.getLanguage() {#woff-getlanguage}

WOFF アプリが実行される環境の言語設定を取得します。

Parameters {#woff-getlanguage-parameter}

なし

Sample {#woff-getlanguage-sample}

woff.getLanguage()

Return value {#woff-getlanguage-response}

WOFF アプリが実行される環境の navigator.language が返されます。

woff.getVersion() {#woff-getversion}

WOFF SDK のバージョンを取得します。

Parameters {#woff-getversion-parameter}

なし

Sample {#woff-getversion-sample}

woff.getVersion()

Return value {#woff-getversion-response}

WOFF SDK のバージョンが文字列として返されます。

woff.getWorksVersion() {#woff-getworksversion}

ユーザーの LINE WORKS バージョンを取得します。

Parameters {#woff-getworksversion-parameter}

なし

Sample {#woff-getworksversion-sample}

woff.getWorksVersion()

Return value {#woff-getworksversion-response}

ユーザーの LINE WORKS バージョンが文字列として返されます。

注意

• PC ブラウザでは利用できません。

woff.isInClient() {#woff-isinclient}

WOFF アプリが LINE WORKS 内の WOFF ブラウザで実行されていることを確認します。

Parameters {#woff-isinclient-parameter}

なし

Sample {#woff-isinclient-sample}

woff.isInClient()

Return value {#woff-isinclient-response}

woff.login() {#woff-login}

WOFF アプリにログインします。

注意

• 外部ブラウザ環境で WOFF アプリを実行する際に必要です。
  • LINE WORKS 内の WOFF ブラウザ上では woff.init() 時に実行されるため不要です。
• woff.login() 実行後は woff.init() を再度実行する必要があります。

Parameters {#woff-login-parameter}

if (!woff.isLoggedIn()) {    woff.login({ redirectUri: "https://example.com/path" });    // Verifies whether domain name and path of the specified URL}// OIDC の scope を指定するif (!woff.isLoggedIn()) {    woff.login({        redirectUri: "https://example.com/path",        scope: "openid profile"    });}// SSO + OIDCif (!woff.isLoggedIn()) {    woff.login({        redirectUri: "https://example.com/path",        domain: "example.com",        scope: "openid"    });}

Return value {#woff-login-response}

なし

woff.isLoggedIn() {#woff-isloggedin}

ユーザーがログインしていることを確認します。

Parameters {#woff-isloggedin-parameter}

なし

Sample {#woff-isloggedin-sample}

woff.isLoggedIn()

Return value {#woff-isloggedin-response}

woff.logout() {#woff-logout}

WOFF アプリからログアウトします。

注意

• ログアウトすると、WOFF のアクセストークンは削除されます。

Parameters {#woff-logout-parameter}

なし

Sample {#woff-logout-sample}

woff.logout()

Return value {#woff-logout-response}

なし

woff.getAccessToken() {#woff-getaccesstoken}

現在のユーザーのアクセストークンを取得します。
この API で取得したアクセストークンを使用して、バックエンドでユーザー情報を取得する等が可能です。

注意

• 外部ブラウザで woff.init() または woff.login() の scope を指定した場合、アクセストークンには要求した scope だけが付与されます。WOFF アプリから呼び出す API の Scope (例: user.read) も scope に含める必要があります。
• woff.init() または woff.login() で scope を指定しない場合、このアクセストークンが持つ権限範囲には、アプリで選択された全ての Scope が含まれます。

外部ブラウザで WOFF アプリを使用する場合は、以下の手順によりアクセストークンを取得できます。

1. WOFF アプリで woff.login() を呼び出す
2. LINE WORKS のログイン画面に遷移し、ユーザーがログインを行う
3. WOFF アプリで再度 woff.init() を呼び出す

Parameters {#woff-getaccesstoken-parameter}

なし

Sample {#woff-getaccesstoken-sample}

woff.getAccessToken()

Return value {#woff-getaccesstoken-response}

現在のユーザーのアクセストークンを文字列として返します。

woff.getIDToken() {#woff-getidtoken}

現在のユーザーの ID トークン (JWT) を、元の文字列のまま取得します。OIDC の scope に openid を含めてログインした場合のみ取得できます。

参考

• ID トークンを使ってサーバーでユーザーを識別する場合は、このメソッドで取得した元の文字列をサーバーに送り、サーバーで ID Token の検証 を行ってから使用してください。

Parameters {#woff-getidtoken-parameter}

なし

Sample {#woff-getidtoken-sample}

const idToken = woff.getIDToken();

Return value {#woff-getidtoken-response}

ID トークン (JWT) を文字列として返します。ID トークンが発行されていない場合は null を返します。

woff.getDecodedIDToken() {#woff-getdecodedidtoken}

現在のユーザーの ID トークンの payload をデコードしたオブジェクトを取得します。OIDC の scope に openid を含めてログインした場合のみ取得できます。

注意

• このメソッドは ID トークンの署名を検証せず、payload をデコードした値だけを返します。画面表示などクライアント側の用途に限って使い、サーバーでユーザーを識別する場合は woff.getIDToken() で取得した元のトークンを検証して使用してください。

Parameters {#woff-getdecodedidtoken-parameter}

なし

Sample {#woff-getdecodedidtoken-sample}

const claims = woff.getDecodedIDToken();if (claims) {  console.log(claims.sub, claims.name, claims.email);}

Return value {#woff-getdecodedidtoken-response}

ID トークンの payload (claim) をオブジェクトとして返します。ID トークンが発行されていない場合は null を返します。

含まれる claim は OIDC の scope によって異なります。詳しくは ID Token の仕様 - Payload を参照してください。

woff.getContext() {#woff-getcontext}

WOFF アプリのコンテキスト情報を取得します。

Parameters {#woff-getcontext-parameter}

なし

Sample {#woff-getcontext-sample}

woff.getContext()

Return value {#woff-getcontext-response}

ReturnSample {#woff-getcontext-response-sample}

{    "viewType": "full",    "endpointUrl": "https://example.com/my-app/",    "permanentLinkPattern": "concat",    "clientId": "_K3ELJuSyEJQlNrkjPPP",    "clientType": "MOBILE_APP"}

woff.getProfile() {#woff-getprofile}

ユーザーのプロフィール情報を取得します。

Parameters {#woff-getprofile-parameter}

なし

Sample {#woff-getprofile-sample}

woff.getProfile()

Return value {#woff-getprofile-response}

Promiseオブジェクトが返されます。

woff.sendMessage() {#woff-sendmessage}

WOFF アプリが開いているトークルームにユーザーに代わってメッセージを送信します。

注意

• この API を利用するには bot または bot.message Scope が必要です。
• この API は、モバイルアプリでのみ利用できます。
• トークルーム以外の画面で WOFF アプリが実行されている場合はメッセージを送信できません。

Parameters {#woff-sendmessage-parameter}

Sample {#woff-sendmessage-parameter-sample}

woff.sendMessage({    content: "Hello、World！"})  .then(()=> {    console.log('message sent');  })  .catch((err)=> {    console.log('error', err);  });

Return value {#woff-sendmessage-response}

Promise オブジェクトを返します。

woff.sendFlexMessage() {#woff-sendflexmessage}

WOFF アプリが開いているトークルームにユーザーに代わって Flexible Template メッセージを送信します。

注意

• この API を利用するには bot または bot.message Scope が必要です。
• この API は、モバイルアプリでのみ利用できます。
• トークルーム以外の画面で WOFF アプリが実行されている場合はメッセージを送信できません。

Parameters {#woff-sendflexmessage-parameter}

Example {#woff-sendflexmessage-example}

woff.sendFlexMessage({    flex: {            "type": "flex",            "altText": file.name,            "contents": {                    "type": "bubble",                    "size": "kilo",                    ...            }    }})  .then(() => {    console.log('message sent');  })  .catch((err) => {    console.log('error', err);  });

Return value {#woff-sendflexmessage-response}

Promise オブジェクトを返します。

woff.scanQR() {#woff-scanqr}

QR コードリーダーを起動して QR コードの読み込みを行います。 QR コードリーダーを有効にするには、Developer Console で WOFF アプリの Scan QR オプションを有効にする必要があります。

woff.scanQR() は以下の環境で動作します。

• iOS: バージョン 3.6.0 以降の LINE WORKS アプリ
• Android: バージョン 3.6.0 以降の LINE WORKS アプリ
• ブラウザ: WebRTC API をサポートしている Web ブラウザ
  • ブラウザで woff.scanQR() を使用する場合は、内部で jsQR ライブラリを使用します。したがって、woff.scanQR() が実行された際に使用される QR コードリーダーは jsQR の仕様に依存します。使用されるライブラリは予告なく更新または変更される場合があります。

Parameters {#woff-scanqr-parameter}

なし

Example {#woff-scanqr-example}

woff.scanQR()  .then((result) => {    // result = { value: "" }  })  .catch((err) => {    console.log('error', err);  });

Return value {#woff-scanqr-response}

Promise オブジェクトを返します。

woff.openWindow() {#woff-openwindow}

LINE WORKS のアプリ内ブラウザまたは外部ブラウザで指定された URL を開きます。外部ブラウザで実行すると正常に動作しない可能性があります。

Parameters {#woff-openwindow-parameter}

Sample {#woff-openwindow-sample}

woff.openWindow({  url: "https://developers.worksmobile.com",  external: true});

Return value {#woff-openwindow-response}

なし

woff.closeWindow() {#woff-closewindow}

WOFF アプリを終了します。外部ブラウザで実行すると正常に動作しない可能性があります。

Parameters {#woff-closewindow-parameter}

なし

Sample {#woff-closewindow-sample}

woff.closeWindow()

Return value {#woff-closewindow-response}

なし

woff.startPipMode() {#woff-startpipmode}

LINE WORKS アプリ (iOS/Android) に、PIP (Picture-in-Picture) モードへの移行を要求します。ビデオ通話など、マルチタスクが必要な WOFF アプリで使用します。

注意

• この API は、モバイルアプリ (LINE WORKS アプリ) でのみ動作します。外部ブラウザや、PIP に対応していないバージョンの LINE WORKS アプリでは何も実行されません。
• PIP モードを終了する API は提供されていません。PIP ウィンドウのドラッグ、終了、復帰は LINE WORKS アプリが処理します。
• この API は、WOFF SDK 3.7.4 以降で利用できます。

Parameters {#woff-startpipmode-parameter}

なし

Sample {#woff-startpipmode-sample}

woff.startPipMode()

Return value {#woff-startpipmode-response}

なし

WOFF SDK errors {#sdk-errors}

WOFF SDKでのエラーは WoffError オブジェクトで返されます。

WoffError object {#woff-error}

Error details {#woff-errorcode}