WOFF Guide

WOFF(NAVER WORKS Front-end Framework)에 대해 소개하고 WOFF 앱을 개발하는 방법에 대해 설명한다.

WOFF 소개 {#about-woff}

WOFF는 NAVER WORKS에서 제공하는 자바스크립트 형태의 웹뷰용 프레임워크이다. WOFF는 NAVER WORKS에 내장된 웹 애플리케이션을 실행하는 플랫폼이며, 여기에서 실행되는 웹 앱을 WOFF 앱이라고 한다. WOFF 앱으로 사용자 ID나 이름과 같은 사용자 정보를 활용한 기능을 만들거나, 메시지방에서 사용자를 대신해 메시지를 보낼 수 있다. WOFF는 SDK 형태로 공개되어 누구나 사용할 수 있다. 단, 앱 등록을 위한 Developer Console 권한이 별도로 필요하다.

WOFF의 장점 {#why-use-woff}

WOFF의 장점은 다음과 같다.

  • 웹 앱이므로 OS(Android, iOS)별로 개발하지 않아도 된다.
  • NAVER WORKS가 설치된 환경에서는 별도의 앱을 설치할 필요 없이 바로 WOFF 앱을 사용할 수 있다.
  • 용도에 따라 WOFF 앱의 크기를 Full, Tall, Compact 중 하나로 선택할 수 있다.
  • 메시지방에서 바로 WOFF 앱을 사용할 수 있다.
  • NAVER WORKS의 로그인 정보가 제공되므로 인앱 브라우저와 외부 브라우저 모두에서 NAVER WORKS 로그인을 유지할 수 있다.

권장 환경 {#operating-environment}

WOFF의 권장 환경은 다음과 같다.

장치권장 환경
iOS 모바일 앱최신 버전. WKWebView가 사용된다.
Android 모바일 앱최신 버전. Android WebView가 사용된다.
PC 앱최신 버전. PC 브라우저에서 실행된다.
PC 브라우저새 탭에서 실행된다.

더 자세한 내용은 NAVER WORKS의 지원 환경을 참고한다.

용어 {#glossary}

다음은 WOFF 앱을 등록하고 개발하기 전에 알아야 할 용어를 설명한다.

항목설명
WOFF IDWOFF 앱 식별자. WOFF 앱을 등록할 때 발행된다. WOFF SDK의 초기화 함수 woff.init()에 기입한다.
WOFF URLWOFF 앱을 실행하는 URL. WOFF ID가 포함되어 있다. Developer Console에서 발급할 수 있으며, Deep Link로 사용할 수 있다.
Endpoint URLWOFF 앱이 위치한 URL. WOFF URL에 액세스하면 Endpoint URL로 리다이렉트된다.
WOFF 브라우저WOFF 앱이 실행되는 전용 브라우저. 사용자가 NAVER WORKS에서 WOFF URL을 열면 WOFF 브라우저가 실행된다.
Access Tokenwoff.init()이 실행되었을 때 WOFF SDK가 발행하는 토큰. 발행 후 12시간이 지나거나 사용자가 WOFF 앱을 닫으면 무효화된다.

WOFF 앱 등록 {#create-woff-app}

WOFF 앱을 사용하려면 먼저 Developer Console에서 WOFF 앱을 등록해야 한다.

WOFF 앱 등록에 필요한 정보 {#settings}

WOFF 앱은 Developer Console의 API 앱 > WOFF 앱에 표시된다. 여기서 등록을 선택해 등록한다.

항목설명
WOFF 이름WOFF 앱의 이름. 여기서 지정한 WOFF 앱 이름은 사용자에게 표시된다.
  • 최대 길이: 20자
Endpoint URLWOFF 앱이 구현된 웹 앱의 URL(예: https://example.com/my-app/?key=value).
WOFF 앱을 실행하면 이 URL로 리다이렉트된다.
  • 최대 길이: 500자
  • HTTPS URL을 등록해야 한다.
  • URL-fragment(#)는 지정할 수 없다.
크기WOFF 앱의 화면 크기. 다음 중 하나를 선택할 수 있다.
  • Full
  • Tall
  • Compact
그림 1 WOFF 앱 화면 크기
Scan QR[woff.scanQR()] (/kr/docs/woff-api#woff-scanqr)기능을 사용하는 경우는 ON으로 한다.
WOFF 리다이렉트 검증WOFF 리다이렉트 검증기능을 사용하는 경우는 ON으로 한다.
ON으로 설정하는 경우에는,Secret Key를 지정합니다.

사용하는 기능에 따라 API Scope을 설정해야 한다. 자세한 내용은 WOFF SDK를 참고한다.
하나의 Developer Console 앱에는 최대 30개의 WOFF 앱을 등록할 수 있다.

WOFF 앱 등록 시 생성되는 정보 {#information-generated}

WOFF 앱을 등록하면 NAVER WORKS 내에서 WOFF Endpoint URL에 연결된 전용 WOFF ID와 WOFF URL이 생성된다.

  • WOFF ID(예: 1654426689BR7LN87b)
  • WOFF URL(예: https://woff.worksmobile.com/woff/1654426689BR7LN87b)

WOFF 앱의 실행 방식 {#open-woff-app}

NAVER WORKS에서 WOFF 앱을 실행하면 WOFF URL에 path, parameter가 추가되어 미리 설정한 EndPoint URL로 전환된다.

WOFF URL: https://woff.worksmobile.com/woff/1654426689BR7LN87bEndpoint URL: https://example.com/my-app/?key=value
추가 정보가 포함된 WOFF URL: https://woff.worksmobile.com/woff/1654426689BR7LN87b/path_A/?key1=value1추가 정보가 포함된 WOFF URL에 액세스할 때 리디렉션되는 URL: https://example.com/my-app/path_A/?key=value&key1=value1

참고

  • Query Parameter를 지정하는 경우 '?' 전에 '/'가 필요하다.
  • URI fragment #은 사용할 수 없다.
  • WOFF를 이용하는 경우 외부 브라우저 설정이 활성화되어 있어도 모바일 앱에서 WOFF 앱이 실행된다.
  • WOFF 앱에서 다른 페이지를 열려면 woff.openWindow()를 실행한다.

WOFF 앱 개발 {#develop-woff-app}

WOFF 앱의 제목을 설정하고 WOFF SDK를 삽입해 WOFF 앱을 개발할 수 있다.

WOFF 앱 제목 설정 {#title-of-woff-app}

WOFF 앱의 제목을 HTML 태그에 title로 작성한다.

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

WOFF SDK 삽입 {#import-woff-sdk}

WOFF SDK URL을 페이지 HTML 소스에 아래와 같이 지정한다.

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

WOFF SDK는 UTF-8로 작성되었으며, 최신 버전은 3.7.1이다. WOFF SDK에 대한 자세한 내용은 WOFF SDK를 참고한다.

WOFF URL 경유 여부 검증 (선택) {#woff-redirect-verification}

[WOFF URL 경유 여부 검증하기] Endpoint URL에 접근하는 사용자가 WOFF URL을 경유하여 도달했는지 검증할 수 있다.

설정 방법

  • Developer Console에서 WOFF URL 생성/수정 시 'WOFF URL 경유 여부 검증' 설정을 활성화하여 Secret Key를 입력 후 저장한다. (Secret Key는 Signature를 검증하기 위해 지정하는 임의의 값으로, ASCII only 80자 이내로 입력한다. )

WOFF Server

해당 설정이 활성화되면, WOFF URL에서 Endpoint로 redirect 시 woffId, timestamp, nonce 값을 SecretKey로 서명하여 (HMAC-SHA256 방식으로 sign) parameter로 전달한다.

항목설명
timestamp사용자가 woff url에 접근한 시각 (unixtime)
nonceReplay attack 방지를 위한 임의의 서버 생성값
signature생성된 signature 값

Endpoint Server

Console에 입력한 Secret Key 값를 서버에서 관리하며, woffId + timestamp + nonce String을 SecretKey로 서명한 후, signature 일치 여부를 확인한다.

유의 사항 {#notes-for-developers}

WOFF 앱 개발 시 다음 사항에 유의한다.

Endpoint URL 정보 {#note-about-endpoint-url}

WOFF 앱이 실행될 때 URL에는 access_token과 같은 중요한 정보가 포함되어 있으므로 로깅 도구와 같은 외부에 URL 정보를 보내지 않아야 한다.

WOFF 앱 초기화 시 URL 변경 제한 {#note-about-initializing}

woff.init()은 WOFF 앱이 실행될 때 URL에 주어진 woff.state나 access_token과 같은 정보를 기반으로 실행된다. 따라서 초기화를 정상적으로 완료하려면 프런트 엔드 프로세싱이 완료되기 전에 URL을 변경하지 않는 것을 권장한다.

대량 요청 제한 {#note-about-bulk-requests}

WOFF 앱으로 NAVER WORKS 플랫폼에 대량 요청을 보내거나, WOFF 앱에 대량으로 액세스하지 않는다.