WOFF SDK

WOFF SDK의 사용방법과 API에 대해 설명한다.

WOFF SDK 사용 방법 {#how-to-use-woff-sdk}

WOFF SDK는 다음과 같은 단계를 거쳐 사용할 수 있다.

1. WOFF 앱 초기화
2. WOFF 앱 실행 환경 확인
3. WOFF 앱에서 다양한 동작 구현
4. WOFF 앱 닫기

WOFF 앱 초기화 {#init-woff-app}

WOFF SDK를 사용하려면 우선 woff.init()으로 WOFF 앱을 초기화해야 한다.

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 앱이 실행되면 URL에 부여된 woff.state나 access_token 정보를 기반으로 woff.init()이 실행된다. 초기화를 정상적으로 완료하려면 프런트 엔드 프로세싱이 완료되기 전에 URL을 변경하지 않아야 한다.
• WOFF 앱이 최초로 실행되는 URL에는 woff.state에 access_token과 같은 민감한 정보가 포함되어 있으므로, Google Analytics 등의 외부 로깅 툴로 URL 정보를 보내지 않아야 한다.

WOFF 앱 실행 환경 확인 {#get-platform-info}

woff.isInClient()와 woff.getOS()를 호출해서 WOFF 앱이 실행되고 있는 환경을 확인한다.

WOFF 앱에서 다양한 동작 구현

WOFF 앱에서 실행될 다양한 동작을 구현한다.

예시 1. 지정된 URL 열기 {#open-windows}

woff.openWindow() 메서드로 NAVER WORKS의 인앱 브라우저 또는 외부 브라우저에서 지정된 URL을 실행한다.

예시 2. 현재 열려 있는 메시지방에 메시지 보내기 {#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 앱이 종료된다.

API 레퍼런스 {#api-reference}

WOFF SDK로 WOFF 앱을 개발하는 데 필요한 API를 설명한다.

woff.init() {#woff-init}

WOFF 앱을 초기화한다. 이 메서드를 호출한 이후에 다른 메서드를 호출할 수 있다. 초기화가 실행될 때 NAVER WORKS로부터 사용자의 Access Token을 가져온다.

다음의 메서드와 속성은 WOFF 앱이 초기화되기 전에도 실행할 수 있다.

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

주의

• woff.init()은 Endpoint URL로 처음 리다이렉트될 때 실행한다. 다른 시점에 실행하면 INIT_FAILED 오류가 발생하며 WOFF 앱을 열 수 없게 된다.
• woff.init()은 WOFF 앱이 실행될 때 URL에 포함된 woff.state나 access_token과 같은 정보를 기반으로 실행된다. 따라서 초기화를 정상적으로 완료하려면 프런트 엔드 프로세싱이 완료되기 전에 URL을 변경하지 않아야 한다.
• WOFF 앱이 최초로 실행되는 URL에는 woff.state에 access_token과 같은 민감한 정보가 포함되어 있으므로, Google Analytics 등의 외부 로깅 툴로 URL 정보를 보내지 않아야 한다.

Parameters {#woff-init-parameter}

Example {#woff-init-sample}

// 기본 형태woff.init(  config,  successCallback,  errorCallback)// Promise 객체를 사용한 방법woff  .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);  });// 콜백을 사용하는 방법woff.init({ woffId: "123456-abcedfg" }, successCallback, errorCallback);

Return value {#woff-init-response}

Promise 객체를 반환한다.

woff.login() {#woff-login}

외부 브라우저 환경에서 로그인 절차를 수행한다. (인앱 브라우저에서는 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}

Return value {#woff-login-response}

없음

woff.logout() {#woff-logout}

로그아웃한다. 이 때, AccessToken 값은 삭제된다.

Parameters {#woff-logout-parameter}

없음

woff.logout()

Return value {#woff-logout-response}

없음

woff.ready {#woff-ready}

woff.init()을 실행해 WOFF 앱의 초기화가 완료된 후 실행할 동작을 정의한다.

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

woff.init() 실행 시 오류가 발생해도 WoffError 객체를 반환하거나 woff.ready를 reject하지 않는다.

woff.getOS() {#woff-getos}

WOFF 앱을 실행하는 OS명을 가져온다. 브라우저명은 가져오지 않는다.

Parameters {#woff-getos-parameter}

없음

Example {#woff-getos-sample}

woff.getOS()

Return value {#woff-getos-response}

woff.getLanguage() {#woff-getlanguage}

WOFF 앱이 실행되는 환경의 언어 설정을 가져온다.

Parameters {#woff-getlanguage-parameter}

없음

Example {#woff-getlanguage-sample}

woff.getLanguage()

Return value {#woff-getlanguage-response}

WOFF 앱이 실행되는 브라우저의 navigator.language를 반환한다.

woff.getVersion() {#woff-getversion}

WOFF 앱이 사용 중인 WOFF SDK의 버전을 가져온다.

Parameters {#woff-getversion-parameter}

없음

Example {#woff-getversion-sample}

woff.getVersion()

Return value {#woff-getversion-response}

WOFF 앱이 사용 중인 WOFF SDK값을 반환한다.

woff.getWorksVersion() {#woff-getworksversion}

사용자의 NAVER WORKS 버전을 가져온다.

Parameters {#woff-getworksversion-parameter}

없음

Example {#woff-getworksversion-sample}

woff.getWorksVersion()

Return value {#woff-getworksversion-response}

사용자의 NAVER WORKS 버전을 반환한다.

주의

• PC 브라우저에서는 이용할 수 없다.

woff.isInClient() {#woff-isinclient}

WOFF 앱이 WOFF 브라우저에서 실행 중인지 확인한다.

Parameters {#woff-isinclient-parameter}

없음

Example {#woff-isinclient-sample}

woff.isInClient()

Return value {#woff-isinclient-response}

woff.isLoggedIn() {#woff-isloggedin}

사용자가 로그인했는지 확인한다.

Parameters {#woff-isloggedin-parameter}

없음

Example {#woff-isloggedin-sample}

woff.isLoggedIn()

Return value {#woff-isloggedin-response}

woff.getChannelId() {#woff.getChannelId}

현재 접속한 채널의 ID를 반환한다. 모바일 환경에서만 작동한다.

Parameters {#woff.getChannelId-parameter}

없음

Example {#woff.getChannelId-sample}

woff.getChannelId()

Return value {#woff.getChannelId-response}

Promise 객체를 반환한다.

woff.getAccessToken() {#woff-getaccesstoken}

현재 사용자의 Access Token을 가져온다. 이 API로 얻은 Access Token을 사용해 WOFF 앱에서 서버로 사용자 정보를 보낼 수 있다.

참고

• 이 Access Token의 권한 범위에는 Developer Console에서 선택한 모든 Scope이 포함된다.

외부 브라우저에서 WOFF 앱이 실행될 때는 다음과 같은 순서로 Access Token이 발급된다.

1. WOFF 앱으로 woff.login()을 호출한다.
2. 사용자가 NAVER WORKS에 로그인한다.
3. WOFF 앱에서 다시 한 번 woff.init()을 호출한다.

Parameters {#woff-getaccesstoken-parameter}

없음

Example {#woff-getaccesstoken-sample}

woff.getAccessToken()

Return value {#woff-getaccesstoken-response}

현재 사용자의 Access Token을 문자열로 반환한다.

woff.getContext() {#woff-getcontext}

WOFF 앱이 실행되는 메시지방의 정보를 가져온다.

Parameters {#woff-getcontext-parameter}

없음

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}

사용자의 프로필 정보를 가져온다.

Parameters {#woff-getprofile-parameter}

없음

Example {#woff-getprofile-sample}

woff.getProfile()

Return value {#woff-getprofile-response}

Promise 객체를 반환한다.

woff.sendMessage() {#woff-sendmessage}

WOFF 앱이 열려 있는 메시지방에 사용자를 대신해 메시지를 보낸다. 메시지방이 아닌 다른 화면에서 WOFF 앱이 실행되면 메시지를 보낼 수 없다.

주의

• 이 API를 사용하려면 bot 또는 bot.message Scope이 필요하다.
• 이 API는 모바일 앱에서만 사용할 수 있다.

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}

Promise 객체를 반환한다.

woff.sendFlexMessage() {#woff-sendflexmessage}

WOFF 앱이 열려 있는 메시지방에 사용자를 대신해 Flex Template 메시지를 보낸다. 메시지방이 아닌 다른 화면에서 WOFF 앱이 실행되면 메시지를 보낼 수 없다.

주의

• 이 API를 사용하려면 bot 또는 bot.message Scope이 필요하다.
• 이 API는 모바일 앱에서만 사용할 수 있다.

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 리더를 활성화하려면 WOFF 앱의 Scan QR 옵션을 설정해야 한다.

woff.scanQR()은 다음과 같은 환경에서 원활히 작동한다.

• iOS: WORKS 버전 3.6.0 이상
• Android: WORKS 버전 3.6.0 이상
• 외부 브라우저: WebRTC API를 지원하는 웹 브라우저(외부 브라우저에서 woff.scanQR()은 내부적으로 jsQR이라는 외부 라이브러리를 사용한다. 따라서 woff.scanQR()이 실행될 때 열리는 QR 리더는 jsQR 스펙에 의존한다. 사용된 라이브러리들은 사전 공지 없이 업데이트되거나 교체될 수 있다.)

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}

NAVER WORKS의 인앱 브라우저 또는 외부 브라우저에서 지정된 URL을 연다. 외부 브라우저에서 실행 시 정상적으로 동작하지 않을 수 있다.

Parameters {#woff-openwindow-parameter}

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

없음

Example {#woff-closewindow-sample}

woff.closeWindow()

Return value {#woff-closewindow-response}

없음

WOFF SDK Error {#sdk-errors}

WOFF SDK에서 발생한 오류를 반환한다.

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