WOFF SDK

This page describes how to use the WOFF SDK and its APIs.

How to use the WOFF SDK {#how-to-use-woff-sdk}

Follow the instructions below to use the WOFF SDK.

1. Initialize the WOFF app.
2. Check the environment for the WOFF app.
3. Implement various actions in the WOFF app.
4. Close the WOFF app.

Initialize the WOFF app {#init-woff-app}

To use the WOFF SDK, you need to first initialize the WOFF app using the woff.init() method.

The woff.init() method initializes the WOFF app, allowing it to call other methods of the WOFF SDK. Run the woff.init() method when the WOFF URL is first redirected to the endpoint URL; otherwise, the INIT_FAILED error occurs and the WOFF app cannot be opened. For woffId in woff.init(), enter the WOFF ID issued when you add the WOFF app in the Developer Console.

woff   .init({     woffId: "123456-abcedfg" //  WOFF ID   })   .then(() => {     // Run the WOFF API   })   .catch((err) => {     // When an error occurs while initializing the app     console.log(err.code, err.message);   });

Caution

• When you open the WOFF app, the woff.init() method is run based on the woff.state or access_token added to the URL. To successfully complete initialization, therefore, do not change the URL before the front-end processing is completed.
• Since the URL at which the WOFF app is first run includes sensitive information such as woff.state or access_token, make sure that it is not exposed to external logging tools such as Google Analytics.

Specify the scope for OIDC login {#init-woff-app-oidc-scope}

In OIDC, the client must explicitly pass openid in the scope parameter of the authentication request. In the WOFF SDK, you can directly specify the OIDC scope with the scope parameter when calling woff.init() and woff.login() (WOFF SDK 3.7.4 or later).

• When scope is specified in an external browser, the WOFF SDK passes the value as is in the authentication request at login.
• In the mobile app (LINE WORKS app), the scope parameter is ignored because the app passes tokens directly.

scope is determined in the following order of priority:

1. woff.login({ scope }): The scope specified when the method is called has the highest priority.
2. woff.init({ scope }): Used if no scope is specified in woff.login().
3. Not specified: If no scope is specified in woff.login() or woff.init(), the scopes selected for the app are granted as they are. However, for apps granted the openid scope, the LINE WORKS authentication server returns an error, so you need to specify scope including openid in woff.login() or woff.init().

Note

• In scope, you can specify only some of the scopes selected for the app. In this case, only the specified scopes are granted to the access token, so you also need to include the scopes of the APIs that the WOFF app calls (e.g., user.read).
• If you specify a scope that is not selected for the app, the authentication request is rejected.
• An ID token is issued only when openid is included. You can get the issued ID token with woff.getIDToken() and woff.getDecodedIDToken().

Check the environment for the WOFF app {#get-platform-info}

Call the woff.isInClient() and woff.getOS() methods to check the environment to run the WOFF app in.

Implement various actions in the WOFF app.

Implement various actions to run in the WOFF app.

Example 1. Open a specified URL {#open-windows}

Call the woff.openWindow() method to open a specified URL in LINE WORKS's in-app browser or an external browser.

Example 1. Send a message to a currently open message room {#send-message}

Call the woff.sendMessage() method to send a text message to the message room where the WOFF app is open, instead of a user. The following code example sends a message, "Hello, Works!" to a message room.

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);     });   }});

Call the woff.sendFlexMessage() method to send a message to the message room where the WOFF app is open, using a flexible template.

Close the WOFF app {#close-woff-app}

Run the woff.closeWindow() method to close the WOFF app.

API reference {#api-reference}

This section describes APIs required to develop a WOFF app using the WOFF SDK.

woff.init() {#woff-init}

Initializes a WOFF app. This method must be called before you call other methods. During the initialization, it gets the user's access token from LINE WORKS.

The following methods and attribute can be run before the WOFF app is initialized.

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

Caution

• Run the woff.init() method when the WOFF URL is first redirected to the endpoint URL; otherwise, the INIT_FAILED error occurs and the WOFF app cannot be opened.
• The woff.init() method is run based on the information such as woff.state or access_token included in the URL when a WOFF app is run. To successfully complete the initialization, therefore, do not change the URL before the front-end processing is completed.
• Since the URL at which the WOFF app is first run includes sensitive information such as woff.state or access_token, make sure that it is not exposed to external logging tools such as Google Analytics.

Parameters {#woff-init-parameter}

Example {#woff-init-sample}

// Default implementationwoff.init(  config,  successCallback,  errorCallback)// Using the Promise objectwoff  .init({    woffId: "123456-abcedfg" // Use own woffId  })  .then(() => {    // Start to use woff's api  })  .catch((err) => {    // Error happens during initialization    console.log(err.code, err.message);  });// Using a callbackwoff.init({ woffId: "123456-abcedfg" }, successCallback, errorCallback);// Specify the OIDC scope (passed at login in an external browser)woff  .init({    woffId: "123456-abcedfg",    scope: "openid profile"  })  .then(() => {    // Start to use woff's api  })  .catch((err) => {    console.log(err.code, err.message);  });

Return value {#woff-init-response}

Returns the Promise object.

woff.login() {#woff-login}

Performs a login in an external browser. (In an in-app browser, this method is not used because a login is performed with woff.init().)
After running the woff.login() method, you need to run the woff.init() method again.

Parameters {#woff-login-parameter}

if (!woff.isLoggedIn()) {    woff.login({ redirectUri: "https://example.com/path" });    // Verifies whether domain name and path of the specified URL}// Specify the OIDC scopeif (!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}

None

woff.logout() {#woff-logout}

Performs a logout. The access token is deleted.

Parameters {#woff-logout-parameter}

None

woff.logout()

Return value {#woff-logout-response}

None

woff.ready {#woff-ready}

Defines an action to perform after the WOFF app is initialized by running the woff.init() method.

woff.ready.then(() => {  // do something you want when woff.init finishes})

Even if an error occurs during the initialization, the app does not return the WoffError object or reject woff.ready.

woff.getOS() {#woff-getos}

Gets the name of the OS on which the WOFF app is run. It does not get the browser name.

Parameters {#woff-getos-parameter}

None

Example {#woff-getos-sample}

woff.getOS()

Return value {#woff-getos-response}

woff.getLanguage() {#woff-getlanguage}

Gets the language settings for the WOFF app.

Parameters {#woff-getlanguage-parameter}

None

Example {#woff-getlanguage-sample}

woff.getLanguage()

Return value {#woff-getlanguage-response}

Returns navigator.language of the browser where the WOFF app is run.

woff.getVersion() {#woff-getversion}

Gets the version of the WOFF SDK that the WOFF app is using.

Parameters {#woff-getversion-parameter}

None

Example {#woff-getversion-sample}

woff.getVersion()

Return value {#woff-getversion-response}

Returns the WOFF SDK version that the WOFF app is using.

woff.getWorksVersion() {#woff-getworksversion}

Gets the LINE WORKS version that the user is using.

Parameters {#woff-getworksversion-parameter}

None

Example {#woff-getworksversion-sample}

woff.getWorksVersion()

Return value {#woff-getworksversion-response}

Returns the LINE WORKS version.

Caution

• This method is not available in the desktop browser.

woff.isInClient() {#woff-isinclient}

Checks if the WOFF app is running in the WOFF browser.

Parameters {#woff-isinclient-parameter}

None

Example {#woff-isinclient-sample}

woff.isInClient()

Return value {#woff-isinclient-response}

woff.isLoggedIn() {#woff-isloggedin}

Checks if the user is logged in.

Parameters {#woff-isloggedin-parameter}

None

Example {#woff-isloggedin-sample}

woff.isLoggedIn()

Return value {#woff-isloggedin-response}

woff.getChannelId() {#woff.getChannelId}

Returns the current channel ID. It is available only on mobile.

Parameters {#woff.getChannelId-parameter}

None

Example {#woff.getChannelId-sample}

woff.getChannelId()

Return value {#woff.getChannelId-response}

Returns the Promise object.

woff.getAccessToken() {#woff-getaccesstoken}

Gets the current user's access token. The WOFF app uses this access token to send user information to the server.

Note

• If scope of woff.init() or woff.login() is specified in an external browser, only the requested scopes are granted to the access token. You also need to include the scopes of the APIs that the WOFF app calls (e.g., user.read) in scope.
• If scope is not specified in woff.init() or woff.login(), the scope of this access token includes all the scopes selected for the app.

When the WOFF app runs in an external browser, an access token is issued by going through the following steps:

1. The WOFF app calls the woff.login() method.
2. The user logs in to LINE WORKS.
3. The WOFF app calls the woff.init() method.

Parameters {#woff-getaccesstoken-parameter}

None

Example {#woff-getaccesstoken-sample}

woff.getAccessToken()

Return value {#woff-getaccesstoken-response}

Returns the current user's access token.

woff.getIDToken() {#woff-getidtoken}

Gets the current user's ID token (JWT) as the original string. It is available only when the user logs in with openid included in the OIDC scope.

Note

• To identify the user on the server with the ID token, send the original string obtained by this method to the server, and use it after verifying it on the server as described in Verify an ID token.

Parameters {#woff-getidtoken-parameter}

None

Example {#woff-getidtoken-sample}

const idToken = woff.getIDToken();

Return value {#woff-getidtoken-response}

Returns the ID token (JWT) as a string. Returns null if no ID token has been issued.

woff.getDecodedIDToken() {#woff-getdecodedidtoken}

Gets an object containing the decoded payload of the current user's ID token. It is available only when the user logs in with openid included in the OIDC scope.

Caution

• This method returns only the decoded payload without verifying the signature of the ID token. Use it only for client purposes such as display. To identify the user on the server, verify and use the original token obtained by woff.getIDToken().

Parameters {#woff-getdecodedidtoken-parameter}

None

Example {#woff-getdecodedidtoken-sample}

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

Return value {#woff-getdecodedidtoken-response}

Returns the payload (claims) of the ID token as an object. Returns null if no ID token has been issued.

The claims included depend on the OIDC scope. For more information, see ID token specification - Payload.

woff.getContext() {#woff-getcontext}

Gets the information of the message room where the WOFF app is running.

Parameters {#woff-getcontext-parameter}

None

Example {#woff-getcontext-sample}

woff.getContext()

Return value {#woff-getcontext-response}

Example {#woff-getcontext-response-sample}

{    "viewType": "external",    "endpointUrl": "https://alpha-ecoapp.worksmobile.com/starter2",    "permanentLinkPattern": "concat",    "clientId": "_K3ELJuSyEJQlNrkjPPP",    "clientType": "PC_WEB"}

woff.getProfile() {#woff-getprofile}

Gets the user's profile information.

Parameters {#woff-getprofile-parameter}

None

Example {#woff-getprofile-sample}

woff.getProfile()

Return value {#woff-getprofile-response}

Returns the Promise object.

woff.sendMessage() {#woff-sendmessage}

Sends a message to the message room where the WOFF app is open, instead of the user. The WOFF app must run in the message room to send a message.

Caution

• The bot or bot.message scope is required to use this API.
• This API is only available for the mobile app.

Parameters {#woff-sendmessage-parameter}

Example {#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}

Returns the Promise object.

woff.sendFlexMessage() {#woff-sendflexmessage}

Sends a Flex Template message to the message room where the WOFF app is open, instead of the user. The WOFF app must run in the message room to send a message.

Caution

• The bot or bot.message scope is required to use this API.
• This API is available only for the mobile app.

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}

Returns the Promise object.

woff.scanQR() {#woff-scanqr}

Runs the QR reader to get the QR string.
To enable the QR reader, you need to set the Scan QR option of the WOFF app.

The requirements to run the woff.scanQR() method are as follows:

• iOS: LINE WORKS 3.6.0 or later
• Android: LINE WORKS 3.6.0 or later
• External browsers: Web browsers supporting WebRTC API (In an external browser, woff.scanQR() internally uses an external library called jsQR, so the QR reader that opens when woff.scanQR() is run depends on the jsQR specifications. The required libraries may be updated or replaced without prior notice.)

Example {#woff-scanqr-example}

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

Return value {#woff-scanqr-response}

Returns the Promise object.

woff.openWindow() {#woff-openwindow}

Opens a specified URL in LINE WORKS's in-app browser or in an external browser. Note that it may not work as expected in an external browser.

Parameters {#woff-openwindow-parameter}

Example {#woff-openwindow-sample}

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

Return value {#woff-openwindow-response}

None

woff.closeWindow() {#woff-closewindow}

Closes the WOFF app. Note that it may not work as expected in an external browser.

Parameters {#woff-closewindow-parameter}

None

Example {#woff-closewindow-sample}

woff.closeWindow()

Return value {#woff-closewindow-response}

None

woff.startPipMode() {#woff-startpipmode}

Requests the LINE WORKS app (iOS/Android) to enter PIP (Picture-in-Picture) mode. Use this method in WOFF apps that need multitasking, such as video calls.

Caution

• This API works only in the mobile app (LINE WORKS app). It does nothing in an external browser or in versions of the LINE WORKS app that do not support PIP.
• No API is provided to exit PIP mode. Dragging, closing, and returning from the PIP window are handled by the LINE WORKS app.
• This API is available in WOFF SDK 3.7.4 or later.

Parameters {#woff-startpipmode-parameter}

None

Example {#woff-startpipmode-sample}

woff.startPipMode()

Return value {#woff-startpipmode-response}

None

WOFF SDK errors {#sdk-errors}

Returns an error that occurred in the WOFF SDK.

{  "code":"INIT_FAILED",  "message":"Failed to init WOFF SDK"}