확장앱 API

네이버 웨일은 확장앱 개발을 위해 아래와 같이 다양한 확장앱 API를 제공합니다.
네이버 웨일 전용 API를 제외한 대부분의 API는 Chrome 확장앱 API와 공통적으로 사용할 수 있습니다.

API
분류
설명
Chrome API와 다른점

whale.alarms
서비스
지정한 주기 혹은 시간에 코드가 실행되도록 예약합니다
없음

whale.bookmarks
브라우저 기능
북마크의 생성, 삭제, 수정 및 폴더 변경 등 북마크에 관한 기능을 제공합니다. 이 API를 이용해 북마크 관리자를 만들 수 있습니다.
없음

whale.action
UI
주소창 오른쪽 툴바 영역에 나타나는 버튼을 제어 할 수 있습니다. 아이콘을 변경하거나 뱃지를 표시할 수도 있고, 팝업이 나타나게 할 수도 있습니다.
없음

whale.browsingData
설정
인터넷 사용 기록을 삭제할 수 있습니다. 설정 > 개인정보 보호 > 인터넷 사용 기록 삭제 영역의 각 항목별 삭제를 수행할 수 있습니다.
없음

whale.commands
설정
확장앱에 단축키를 부여할 수 있습니다.
없음

whale.contentSettings
설정
쿠키, 자바스크립트, 마이크 등 웹 사이트에서 요청한 정보를 제공할 것인지 설정할 수 있습니다. 설정 > 개인정보 보호 > 콘텐츠 설정에서 확인할 수 있는 항목을 제어할 수 있습니다.
없음

whale.contextMenus
UI
마우스 오른쪽 버튼을 클릭하면 나타나는 콘텍스트 메뉴를 만들 수 있습니다. 페이지, 링크, 이미지 등 클릭한 위치에 따라 서로 다른 메뉴를 표시할 수 있습니다.
없음

whale.cookies
서비스
쿠키를 제어하거나 변경시 이벤트를 수신할 수 있습니다
없음

whale.debugger
개발자도구
특정 탭의 네트워크 통신, JavaScript 디버깅, DOM · CSS 변형 등 디버그를 위한 원격 디버깅 프로토콜을 사용할 수 있습니다. sendCommand() 메소드와 onEvent 핸들러 함수를 이용해 개발자도구에서 제공하는 개별 기능을 명령 단위로 수행할 수 있습니다.
없음

whale.declarativeContent
서비스
웹 페이지에 대한 접근 권한 요청없이 특정 페이지의 콘텐트 혹은 상태에 의존적인 동작을 수행할 수 있습니다.
없음

whale.declarativeNetRequest
서비스
선언적 규칙을 지정하여 네트워크 요청을 차단하거나 수정할 수 있습니다.
없음

whale.desktopCapture
캡쳐
화면, 윈도우 또는 탭의 콘텐츠를 캡쳐할 수 있습니다.
없음

whale.devtools.inspectedWindow
개발자도구
개발자도구를 이용한 검사(Inspect)가 진행중인 윈도우에서 코드를 실행하거나 페이지를 새로고침 하는 등의 작업을 수행할 수 있습니다.
없음

whale.devtools.network
개발자도구
개발자도구 > 네트워크 패널에서 수신하는 정보들을 수신할 수 있습니다.
없음

whale.devtools.panels
개발자도구
개발자도구에 새로운 패널을 추가하거나 기존의 패널에 접근할 수 있습니다.
없음

whale.devtools.recorder
개발자도구
개발자도구 > Recorder 패널을 확장할 수 있습니다.
없음

whale.downloads
브라우저 기능
지정한 URL의 파일 다운로드, 진행중인 다운로드의 제어 및 검색 등 파일 다운로드에 관련된 기능을 사용할 수 있습니다.
없음

whale.events
자료형
웨일 브라우저 API에서 사용되는 공통 이벤트 자료형을 포함하는 네임스페이스입니다.
없음

whale.extension
확장앱
서로 다른 확장앱 사이에 메시지를 교환하거나, 현재 확장앱에 관한 정보를 얻을 수 있습니다.
없음

whale.fontSettings
설정
글꼴 관련 설정을 제어할 수 있습니다.
없음

whale.history
브라우저 기능
방문 기록의 생성, 삭제 및 검색 등 방문 기록에 관한 기능을 제공합니다. 이 API를 이용해 방문 기록 페이지를 만들 수 있습니다.
없음

whale.i18n
유틸리티
다국어 지원을 위한 기능을 제공합니다.
없음

whale.identity
서비스
Google 계정을 OAuth2 연동하기 위한 API입니다. 웨일에서는 launchWebAuthFlow()만 사용할 수 있습니다.
부분 지원

whale.idle
서비스
시스템의 유휴 상태(Idle) 여부를 확인하거나 변화를 감지할 수 있습니다.
없음

whale.management
확장앱
설치되어 있는 확장앱 정보를 얻어 제어할 수 있습니다.
없음

whale.notifications
UI
시스템 트레이에 알림창을 표시할 수 있습니다.
없음

whale.offscreen
유틸리티
서비스 워커에서 DOM API를 사용하기 위해 화면에 보이지 않는(오프스크린) 문서를 만들고 관리할 수 있습니다.
없음

whale.omnibox
UI
주소창에서 특정 키워드를 입력하면 확장앱이 주소창 영역에 관여하게 할 수 있습니다.
없음

whale.pageCapture
캡쳐
지정한 탭의 웹 페이지를 MHTML 형식으로 저장할 수 있습니다.
없음

whale.permissions
확장앱
매니페스트에 optional_permissions로 정의한 추가 권한을 사용자에게 요청할 수 있습니다
없음

whale.power
설정
전원 관리 기능을 제어할 수 있습니다.
없음

whale.privacy
설정
개인정보 보호 관련 설정을 제어할 수 있습니다.
없음

whale.proxy
설정
프록시 관련 설정을 제어할 수 있습니다.
없음

whale.runtime
확장앱
백그라운드 페이지 검색, 매니페스트 확인 및 확장앱 수명주기에 관한 이벤트 수신, 메시지 교환 등의 기능을 제공합니다.
없음

whale.scripting
유틸리티
다양한 컨텍스트에서 스크립트를 실행합니다.
없음

whale.sessions
서비스
같은 계정으로 웨일을 사용중인 다른 브라우징 세션에 관련된 기능을 제공합니다.
지원되지 않음

whale.storage
서비스
데이터 저장소 기능을 제공합니다. 데이터 변경시 이벤트를 수신할 수 있습니다. 이 API를 이용해 저장한 데이터는 쿠키, 웹 스토리지 등 인터넷 사용 기록과는 별도로 관리됩니다.
없음

whale.system.cpu
시스템
시스템 CPU 관련 정보를 얻을 수 있습니다.
없음

whale.system.memory
시스템
시스템 메모리 관련 정보를 얻을 수 있습니다.
없음

whale.system.storage
시스템
시스템 연결된 이동식 저장매체에 대한 정보를 얻을 수 있습니다. 새로운 이동식 저장매체가 연결되거나, 이미 연결되어 있던 매체가 연결 해제되는 경우 이벤트를 수신할 수 있습니다.
없음

whale.tabCapture
탭 · 창
지정한 탭의 미디어 스트림을 캡쳐할 수 있습니다
없음

whale.tabs
탭 · 창
새로운 탭을 생성하거나 이미 생성된 탭을 제어할 수 있습니다.
없음

whale.topSites
브라우저 기능
새 탭 페이지의 "자주 가는 사이트" 목록을 얻거나 수정, 검색 할 수 있습니다.
삭제, 수정, 검색 등 추가 메소드 제공

whale.types
자료형
웨일 브라우저 API에서 사용되는 자료형을 포함하고 있는 네임스페이스입니다.
없음

whale.webNavigation
네트워크
웹 탐색 요청을 수신하여 제어할 수 있습니다.
없음

whale.webRequest
네트워크
웹 요청을 감지하여 차단, 수정 및 간섭할 수 있습니다.
없음

whale.windows
탭 · 창
새로운 창을 생성하거나 이미 생성된 창을 제어할 수 있습니다.
없음

whale.sidebarAction
UI
사이드바 영역에 버튼을 표시할 수 있습니다. action과 비슷하며 사이드바 영역에 표시한다는 점이 다릅니다.
웨일 전용

API	분류	설명	Chrome API와 다른점
whale.alarms	서비스	지정한 주기 혹은 시간에 코드가 실행되도록 예약합니다	없음
whale.bookmarks	브라우저 기능	북마크의 생성, 삭제, 수정 및 폴더 변경 등 북마크에 관한 기능을 제공합니다. 이 API를 이용해 북마크 관리자를 만들 수 있습니다.	없음
whale.action	UI	주소창 오른쪽 툴바 영역에 나타나는 버튼을 제어 할 수 있습니다. 아이콘을 변경하거나 뱃지를 표시할 수도 있고, 팝업이 나타나게 할 수도 있습니다.	없음
whale.browsingData	설정	인터넷 사용 기록을 삭제할 수 있습니다. 설정 > 개인정보 보호 > 인터넷 사용 기록 삭제 영역의 각 항목별 삭제를 수행할 수 있습니다.	없음
whale.commands	설정	확장앱에 단축키를 부여할 수 있습니다.	없음
whale.contentSettings	설정	쿠키, 자바스크립트, 마이크 등 웹 사이트에서 요청한 정보를 제공할 것인지 설정할 수 있습니다. 설정 > 개인정보 보호 > 콘텐츠 설정에서 확인할 수 있는 항목을 제어할 수 있습니다.	없음
whale.contextMenus	UI	마우스 오른쪽 버튼을 클릭하면 나타나는 콘텍스트 메뉴를 만들 수 있습니다. 페이지, 링크, 이미지 등 클릭한 위치에 따라 서로 다른 메뉴를 표시할 수 있습니다.	없음
whale.cookies	서비스	쿠키를 제어하거나 변경시 이벤트를 수신할 수 있습니다	없음
whale.debugger	개발자도구	특정 탭의 네트워크 통신, JavaScript 디버깅, DOM · CSS 변형 등 디버그를 위한 원격 디버깅 프로토콜을 사용할 수 있습니다. `sendCommand()` 메소드와 `onEvent` 핸들러 함수를 이용해 개발자도구에서 제공하는 개별 기능을 명령 단위로 수행할 수 있습니다.	없음
whale.declarativeContent	서비스	웹 페이지에 대한 접근 권한 요청없이 특정 페이지의 콘텐트 혹은 상태에 의존적인 동작을 수행할 수 있습니다.	없음
whale.declarativeNetRequest	서비스	선언적 규칙을 지정하여 네트워크 요청을 차단하거나 수정할 수 있습니다.	없음
whale.desktopCapture	캡쳐	화면, 윈도우 또는 탭의 콘텐츠를 캡쳐할 수 있습니다.	없음
whale.devtools.inspectedWindow	개발자도구	개발자도구를 이용한 검사(Inspect)가 진행중인 윈도우에서 코드를 실행하거나 페이지를 새로고침 하는 등의 작업을 수행할 수 있습니다.	없음
whale.devtools.network	개발자도구	개발자도구 > 네트워크 패널에서 수신하는 정보들을 수신할 수 있습니다.	없음
whale.devtools.panels	개발자도구	개발자도구에 새로운 패널을 추가하거나 기존의 패널에 접근할 수 있습니다.	없음
whale.devtools.recorder	개발자도구	개발자도구 > Recorder 패널을 확장할 수 있습니다.	없음
whale.downloads	브라우저 기능	지정한 URL의 파일 다운로드, 진행중인 다운로드의 제어 및 검색 등 파일 다운로드에 관련된 기능을 사용할 수 있습니다.	없음
whale.events	자료형	웨일 브라우저 API에서 사용되는 공통 이벤트 자료형을 포함하는 네임스페이스입니다.	없음
whale.extension	확장앱	서로 다른 확장앱 사이에 메시지를 교환하거나, 현재 확장앱에 관한 정보를 얻을 수 있습니다.	없음
whale.fontSettings	설정	글꼴 관련 설정을 제어할 수 있습니다.	없음
whale.history	브라우저 기능	방문 기록의 생성, 삭제 및 검색 등 방문 기록에 관한 기능을 제공합니다. 이 API를 이용해 방문 기록 페이지를 만들 수 있습니다.	없음
whale.i18n	유틸리티	다국어 지원을 위한 기능을 제공합니다.	없음
whale.identity	서비스	Google 계정을 OAuth2 연동하기 위한 API입니다. 웨일에서는 `launchWebAuthFlow()`만 사용할 수 있습니다.	부분 지원
whale.idle	서비스	시스템의 유휴 상태(Idle) 여부를 확인하거나 변화를 감지할 수 있습니다.	없음
whale.management	확장앱	설치되어 있는 확장앱 정보를 얻어 제어할 수 있습니다.	없음
whale.notifications	UI	시스템 트레이에 알림창을 표시할 수 있습니다.	없음
whale.offscreen	유틸리티	서비스 워커에서 DOM API를 사용하기 위해 화면에 보이지 않는(오프스크린) 문서를 만들고 관리할 수 있습니다.	없음
whale.omnibox	UI	주소창에서 특정 키워드를 입력하면 확장앱이 주소창 영역에 관여하게 할 수 있습니다.	없음
whale.pageCapture	캡쳐	지정한 탭의 웹 페이지를 MHTML 형식으로 저장할 수 있습니다.	없음
whale.permissions	확장앱	매니페스트에 `optional_permissions`로 정의한 추가 권한을 사용자에게 요청할 수 있습니다	없음
whale.power	설정	전원 관리 기능을 제어할 수 있습니다.	없음
whale.privacy	설정	개인정보 보호 관련 설정을 제어할 수 있습니다.	없음
whale.proxy	설정	프록시 관련 설정을 제어할 수 있습니다.	없음
whale.runtime	확장앱	백그라운드 페이지 검색, 매니페스트 확인 및 확장앱 수명주기에 관한 이벤트 수신, 메시지 교환 등의 기능을 제공합니다.	없음
whale.scripting	유틸리티	다양한 컨텍스트에서 스크립트를 실행합니다.	없음
whale.sessions	서비스	같은 계정으로 웨일을 사용중인 다른 브라우징 세션에 관련된 기능을 제공합니다.	지원되지 않음
whale.storage	서비스	데이터 저장소 기능을 제공합니다. 데이터 변경시 이벤트를 수신할 수 있습니다. 이 API를 이용해 저장한 데이터는 쿠키, 웹 스토리지 등 인터넷 사용 기록과는 별도로 관리됩니다.	없음
whale.system.cpu	시스템	시스템 CPU 관련 정보를 얻을 수 있습니다.	없음
whale.system.memory	시스템	시스템 메모리 관련 정보를 얻을 수 있습니다.	없음
whale.system.storage	시스템	시스템 연결된 이동식 저장매체에 대한 정보를 얻을 수 있습니다. 새로운 이동식 저장매체가 연결되거나, 이미 연결되어 있던 매체가 연결 해제되는 경우 이벤트를 수신할 수 있습니다.	없음
whale.tabCapture	탭 · 창	지정한 탭의 미디어 스트림을 캡쳐할 수 있습니다	없음
whale.tabs	탭 · 창	새로운 탭을 생성하거나 이미 생성된 탭을 제어할 수 있습니다.	없음
whale.topSites	브라우저 기능	새 탭 페이지의 "자주 가는 사이트" 목록을 얻거나 수정, 검색 할 수 있습니다.	삭제, 수정, 검색 등 추가 메소드 제공
whale.types	자료형	웨일 브라우저 API에서 사용되는 자료형을 포함하고 있는 네임스페이스입니다.	없음
whale.webNavigation	네트워크	웹 탐색 요청을 수신하여 제어할 수 있습니다.	없음
whale.webRequest	네트워크	웹 요청을 감지하여 차단, 수정 및 간섭할 수 있습니다.	없음
whale.windows	탭 · 창	새로운 창을 생성하거나 이미 생성된 창을 제어할 수 있습니다.	없음
whale.sidebarAction	UI	사이드바 영역에 버튼을 표시할 수 있습니다. `action`과 비슷하며 사이드바 영역에 표시한다는 점이 다릅니다.	웨일 전용

호환성

네이버 웨일 브라우저 API는 Google Chrome 브라우저를 포함하여 Mozilla FireFox, Microsoft Edge 등이 지원하는 브라우저 호환 확장앱 API 규격(W3C Draft Community Group Browser Extensions API)을 지원합니다. 특히 네이버 웨일의 whale.* 네임스페이스 뿐 아니라 chrome.* 네임스페이스도 지원하므로 Google 서비스 연동이 필요한 일부 Chrome 전용 API를 사용하는 경우가 아니라면 기존 Chrome 확장 프로그램도 수정없이 네이버 웨일에서 동작할 수 있습니다.

제약사항

콘텐츠 스크립트는 일부 API만 제한적으로 사용할 수 있습니다. 매니페스트에 필요한 권한을 설정했음에도 해당 API가 존재하지 않는다는 오류를 만나는 경우 콘텐츠 스크립트에서 사용 가능한 API인지 확인해 주세요.

매니페스트

확장앱의 이름, 버전 및 사용하는 권한 등의 정보는 일정 규칙을 가진 JSON 형식으로 작성해야 하며 이것을 이를 매니페스트라고 합니다. 모든 확장앱은 확장앱 최상위 경로에 매니페스트를 기록한 manifest.json 파일을 가집니다. 아래는 설정할 수 있는 매니페스트 예시입니다. 각각의 키 이름을 클릭하면 자세한 정보를 확인할 수 있습니다.

일부 네이버 웨일 전용 매니페스트 키를 제외하면 웨일 브라우저 확장앱의 매니페스트와 같습니다.

최소 매니페스트

확장앱 구성에 필요한 최소한의 필수 정보는 아래와 같습니다.
아래 매니페스트만으로도 설치할 수 있는 확장앱이 되지만 아무런 기능을 하지 않습니다.

{
  "manifest_version": 3,
  "name": "Minimal Manifest",
  "version": "1.0.0"
}

콘텐츠 스크립트 등록

아래는 특정 웹 사이트에 확장앱 내에 포함된 자바스크립트 파일을 실행하는 매니페스트 구성 예시입니다.
콘텐츠 스크립트 문서에서 자세한 내용을 확인하실 수 있습니다.

{
  "manifest_version": 3,
  "name": "Run script automatically",
  "version": "1.0",
  "content_scripts": [
    {
      "js": [
        "content-script.js"
      ],
      "matches": [
        "https://*.example.com//"
      ]
    }
  ]
}

매니페스트 키

manifest_version

매니페스트 파일 형식의 버전을 지정하는 정수입니다. 유일하게 지원되는 값은 3입니다.

name

웨일 스토어, 확장앱 설치 대화창, 사용자의 확장앱 관리자 페이지(whale://extensions)에서 확장앱을 식별하는 문자열입니다.
최대 길이는 영문 기준 45자입니다. 언어별 이름 사용에 관한 자세한 내용은 다국어화를 참고하세요.

version

확장앱의 버전 번호를 식별하는 문자열입니다. 버전 번호 형식에 대한 자세한 내용은 버전을 참조하세요.

description

웨일 스토어와 사용자의 확장앱 관리자 페이지에서 확장앱을 설명하는 문자열입니다. 최대 길이는 영문 기준 132자입니다. 언어별 설명에 관한 자세한 내용은 다국어화를 참고하세요.

웨일 스토어에 등록하려면 이 항목이 필요합니다

icons

확장앱을 나타내는 하나 이상의 아이콘입니다. 권장되는 파일 형식과 크기에 관한 내용은 아이콘을 참고하세요.

웨일 스토어에 등록하려면 이 항목이 필요합니다

action

툴바 영역에 노출되는 확장앱 버튼과 동작을 정의합니다. 자세한 내용은 whale.action를 참조하세요.

이 키는 sidebar_action 키와 동시에 사용할 수 없습니다.

background

이벤트 핸들러 역할을 하는 확장앱의 서비스 워커가 포함된 자바스크립트 파일을 지정합니다.

자세한 내용은 확장앱 서비스 워커를 참조하세요.

chrome_settings_overrides

일부 기본 설정값을 재정의할 수 있습니다. 자세한 내용은 설정 재정의를 참고하세요.

chrome_url_overrides

일부 기본 페이지를 재정의할 수 있습니다. 자세한 내용은 페이지 재정의를 참고하세요.

commands

확장앱 내에 단축키를 정의합니다. 자세한 내용은 whale.commands를 참고하세요.

content_scripts

사용자가 특정 웹페이지를 열 때 사용할 자바스크립트 또는 CSS 파일을 지정합니다. 자세한 내용은 콘텐츠 스크립트를 참고하세요.

content_security_policy

확장앱이 사용할 수 있는 스크립트, 스타일, 기타 리소스에 대한 제한사항을 정의합니다. 자세한 내용은 콘텐츠 보안 정책을 참고하세요.

cross_origin_embedder_policy

확장앱 페이지에 교차 출처 리소스 삽입을 구성하는 Cross-Origin-Embedder-Policy HTTP 헤더의 값을 지정합니다.

cross_origin_opener_policy

최상위 확장앱 페이지가 교차 출처 문서와 탐색 컨텍스트 그룹을 공유하지 않도록 하는 Cross-Origin-Opener-Policy HTTP 헤더의 값을 지정합니다.

declarative_net_request

네트워크 요청의 차단 및 수정을 허용하는 declarativeNetRequest API의 정적 규칙을 정의합니다.

default_locale

여러 언어를 지원하는 확장앱의 기본 언어를 정의하는 문자열입니다. en, ko_KR 등을 예로 들 수 있습니다.
이 키는 다국어화 된 확장앱에 필요하며 그렇지 않은 확장앱에 사용하면 오류가 발생합니다. 자세한 내용은 다국어화를 참고하세요.

devtools_page

DevTools API를 사용하는 페이지를 정의합니다.

export

확장앱에서 리소스를 내보내도록 허용합니다. 자세한 내용은 내보내기를 참조하세요.

externally_connectable

확장앱에 연결할 수 있는 다른 페이지 및 확장앱을 지정합니다. 자세한 내용은 externally_connectable를 참고하세요.

homepage_url

확장앱의 홈페이지의 URL을 지정하는 문자열입니다. 정의되지 않은 경우 홈페이지는 기본적으로 확장앱의 웨일 스토어 페이지 주소가 사용됩니다.

host_permissions

확장앱이 상호작용할 수 있는 웹페이지를 나열하며 URL 일치 패턴을 사용하여 정의됩니다. 이러한 사이트에 관한 사용자 권한은 설치 시 요청됩니다. 자세한 내용은 호스트 권한을 참고하세요.

import

리소스를 확장앱으로 가져올 수 있도록 허용합니다. 자세한 내용은 가져오기를 참조하세요.

incognito

시크릿창에서 확장앱이 작동하는 방식을 정의합니다. 지원되는 값은 spanning, split, not_allowed입니다.

minimum_whale_version

확장앱을 설치할 수 있는 가장 오래된 웨일 버전을 정의합니다. 이 값은 기존 웨일 브라우저 버전 문자열의 하위 문자열(예: 3 또는 3.23.214.17)이어야 합니다. 웨일 버전이 최소 버전보다 낮은 사용자에게는 웨일 스토어에 ‘호환되지 않음’ 경고가 표시되며 확장앱을 설치할 수 없습니다. 이 확장앱을 기존 확장앱에 추가하면 웨일 버전이 이전 버전인 사용자는 확장앱이 자동 업데이트되지 않습니다.

omnibox

확장앱이 웨일 주소 표시줄에 키워드를 등록하도록 허용합니다. 자세한 내용은 whale.omnibox을 참고하세요.

optional_host_permissions

확장앱의 선택적 호스트 권한을 선언합니다.

optional_permissions

확장앱의 선택적 권한을 선언합니다.

options_page

확장앱이 옵션 페이지로 사용할 options.html 파일의 경로를 지정합니다. 자세한 내용은 사용자에게 옵션 제공을 참고하세요.

options_ui

사용자가 웨일 확장앱 페이지에서 확장앱 옵션을 변경할 수 있는 HTML 파일의 경로를 지정합니다. 자세한 내용은 삽입된 옵션을 참고하세요.

permissions

특정 확장앱 API를 사용 설정합니다. 일반적인 설명은 권한을 참조하세요. 개별 API의 참조 페이지에는 필요한 권한이 나와 있습니다.

requirements

확장앱을 사용하는 데 필요한 기술을 나열합니다. 지원되는 요구사항 목록은 요구사항을 참고하세요.

sandbox

확장앱 API에 액세스할 수 없거나 샌드박스가 설정되지 않은 페이지에 직접 액세스할 수 없는 확장앱 페이지 집합을 정의합니다. 자세한 내용은 샌드박스를 참고하세요.

short_name

문자 공간이 제한될 때 사용할 단축된 버전의 확장앱 이름이 포함된 문자열입니다. 최대 길이는 12자(영문 기준)입니다.
이 속성이 정의되지 않은 경우 ‘name’ 키의 잘린 버전이 대신 표시됩니다.

웨일 사이드바 확장앱 버튼과 동작을 정의하기 위해 사용합니다. 자세한 내용은 whale.sidebarAction을 참고하세요.

이 키는 action 키와 동시에 사용할 수 없습니다.

storage

관리형 스토리지 영역의 JSON 스키마를 선언합니다. 자세한 내용은 저장소 영역에 관한 매니페스트를 참고하세요.

tts_engine

확장앱을 TTS(텍스트 음성 변환) 엔진으로 등록합니다. 자세한 내용은 whale.ttsEngine API를 참고하세요.

update_url

확장앱의 업데이트 페이지 URL이 포함된 문자열입니다. 웨일 스토어 외부에서 확장앱을 호스팅하는 경우 이 키를 사용합니다.

version_name

확장앱의 버전을 설명하는 문자열입니다. 예를 들어 1.0 beta, build rc2가 있습니다. 지정하지 않으면 ‘버전’ 값이 확장앱 관리자 페이지에 대신 표시됩니다.

web_accessible_resources

웹페이지 또는 다른 확장앱에서 액세스할 수 있는 확장앱 내에서 파일을 정의합니다. 자세한 내용은 리소스 참조를 확인하세요.

whale.sidebarAction

사이드바는 웨일 브라우저의 대표적인 기능 중 하나로 창의 한쪽을 밀거나 덮는 형태로 표시되는 독립된 영역입니다. 사용자의 설정에 따라 창의 좌측 혹은 우측에 위치하며, 너비는 기본 390픽셀에서 최대 590픽셀 범위 내에서 사용자가 직접 조정할 수 있습니다. 사이드바앱은 주소창 오른쪽 툴바 영역이 아닌 사이드바 영역에 버튼이 표시됩니다.

웨일 사이드바

매니페스트

manifest.json 파일에 sidebar_action 속성을 정의한 확장앱을 사이드바앱이라고 구분하여 부릅니다.

{
  ...
  "sidebar_action": {
    "default_page": "sidebar.html",  // 필수
    "default_icon": {                // 필수
        "16": "images/icon16.png"
    },
    // 선택
    "default_title": "사이드바앱",
    "use_navigation_bar": true,      // 기본값 true
    "mobile_user_agent": true        // 기본값 true
  }
  ...
}

default_icon 사이드바앱 실행 아이콘 경로
default_page 사이드바앱 실행시 표시할 페이지 HTML 경로. URL은 사용할 수 없습니다.
default_title 아이콘에 마우스를 올렸을 때 보이는 툴팁 문자열
use_navigation_bar 하단 네비게이션 바 표시 여부. 기본값은 true

mobile_user_agent 모바일 User Agent 사용 여부. 기본값은 true




  mobile_user_agent: true
  mobile_user_agent: false




  
      Mozilla/5.0 (Linux; Android 7.1.2; Nexus 6P Build/WHALE)

      AppleWebKit/537.36 (KHTML, like Gecko)

      Chrome/65.0.3325.220 Whale/1.3.53.4

      Mobile Safari/537.36 sidebar
  
  
      Mozilla/5.0 (Windows NT 6.1; Win64; x64)

      AppleWebKit/537.36 (KHTML, like Gecko)

      Chrome/65.0.3325.220 Whale/1.3.53.4

      Safari/537.36 sidebar

mobile_user_agent: true	mobile_user_agent: false
Mozilla/5.0 (Linux; Android 7.1.2; Nexus 6P Build/WHALE) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.220 Whale/1.3.53.4 Mobile Safari/537.36 sidebar	Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.220 Whale/1.3.53.4 Safari/537.36 sidebar

메소드

show

사이드바 영역을 열고 포커스를 주는 메소드입니다. 이미 사이드바가 열려있다면 포커스만 옮겨줍니다.

whale.sidebarAction.show(Integer windowId, Object details, Function callback);

인자

Integer windowId (optional): 대상 윈도우의 ID. 지정하지 않으면 현재 윈도우.
Object details (optional)
- String url (optional): 사이드바 영역에 표시할 페이지 URL. 지정하지 않으면 매니페스트에 정의한 default_page.
- Boolean reload (optional): url 인자와 현재 URL이 같을 때에도 페이지를 새로고침 할 것인지 여부. 기본값 false

Function callback (optional): 아래와 같은 형식의 콜백함수:

function (Integer windowId) { ... } // 사이드바가 제어되고 있는 대상 윈도우의 ID

hide

사이드바를 닫습니다. 현재 확장앱에 포커스가 있는 상황에만 동작합니다.

whale.sidebarAction.hide(Integer windowId, Function callback);

인자

Integer windowId (optional): 대상 윈도우의 ID. 지정하지 않으면 현재 윈도우.

Function callback (optional): 아래와 같은 형식의 콜백함수:

function (Integer windowId) { ... } // 사이드바가 제어되고 있는 대상 윈도우의 ID

setTitle

확장앱 아이콘에 마우스를 올렸을 때 나타나는 툴팁 문자열을 변경합니다.
sidebar_action 에서 default_title 속성으로 지정하는 영역입니다.
열려 있는 모든 윈도우에 동시 적용됩니다.

whale.sidebarAction.setTitle(Object details);

인자

Object details
- String title

getTitle

확장앱 아이콘에 마우스를 올렸을 때 나타나는 툴팁 문자열을 반환합니다.
sidebar_action 에서 default_title 속성으로 지정한 영역입니다.

whale.sidebarAction.getTitle(Function callback);

인자

Function callback: 아래와 같은 형식의 콜백함수
function (String result) { ... }

setIcon

확장앱 아이콘을 동적으로 변경합니다. 열려 있는 모든 윈도우에 동시 적용됩니다.

whale.sidebarAction.setIcon(Object details);

인자

Object details
- ImageDataType icon

setPage

확장앱 아이콘이 클릭되었을 때, 로딩되는 페이지 리소스의 경로를 변경합니다.

whale.sidebarAction.setPage(Object details);

인자

Object details
- String page - html 파일의 리소스 경로. 빈 문자열(‘’)로 설정하면 사이드바에 빈화면이 보입니다.

getPage

사이드바 확장앱 아이콘이 클릭되었을 때, 로딩되는 페이지 리소스의 경로를 반환합니다.

whale.sidebarAction.getPage(Function callback);

인자

Function callback: 아래와 같은 형식의 콜백함수
function (String result) { ... }

setBadgeText

확장앱 아이콘 위에 표시되는 뱃지의 문자열을 변경합니다. 열려 있는 모든 윈도우에 동시 적용됩니다.

whale.sidebarAction.setBadgeText(Object details);

인자

Object details
- string text

getBadgeText

사이드바 확장앱 아이콘 위에 표시되는 뱃지의 문자열을 반환합니다.

whale.sidebarAction.getBadgeText(Function callback);

인자

Function callback : 아래와 같은 형식의 콜백함수
function (String result) { ... }

setBadgeBackgroundColor

확장앱 아이콘 위에 표시되는 뱃지의 배경 색상을 변경합니다. 열려 있는 모든 윈도우에 동시 적용됩니다.

whale.sidebarAction.setBadgeBackgroundColor(Object details);

인자

Object details
- String or ColorArray color - 뱃지 배경 색상. RGBA 색상값 배열([255, 0, 0, 255]) 혹은 HEX 색상 표현 문자열(#FF0000).

getBadgeBackgroundColor

확장앱 아이콘 위에 표시되는 뱃지의 배경색상을 반환합니다.

whale.sidebarAction.getBadgeBackgroundColor(Function callback);

인자

Function callback : 아래와 같은 형식의 콜백함수

function (ColorArray color) { ... } // 뱃지 배경 색상. RGBA 색상값 배열 [R, G, B, A]

dock

팝업 윈도우 또는 특정 탭을 사이드바에 도킹합니다.

whale.sidebarAction.dock(Integer windowId, Object details, Function callback);

인자

Integer windowId : 도킹하려는 대상 팝업 윈도우의 ID 혹은 대상 탭이 속한 윈도우의 ID.
Object details (optional)
- Integer parentWindowId (optional) : 부모 윈도우의 ID. 지정하지 않으면 마지막 사용된 윈도우의 사이드바로 보냅니다. 탭을 도킹하는 경우, parentWindowId를 지정하지 않으면 해당 탭이 속한 윈도우의 사이드바로 보냅니다.
- Integer tabId (optional) : 도킹하고자 하는 대상이 팝업 윈도우가 아니고 탭인 경우, 탭 ID를 지정해야합니다.

Function callback : 아래와 같은 형식의 콜백함수

function (Integer windowId) { ... } // 도킹이 된 부모 윈도우의 ID

도킹 후에는 팝업 윈도우의 ID는 더 이상 유효하지 않습니다.

undock

도킹된 윈도우나 탭을 사이드바에서 떼어냅니다. 도킹 전 팝업 윈도우였으면 팝업으로, 탭이었으면 탭으로 복원합니다.

whale.sidebarAction.undock(Integer parentWindowId, Function callback);

인자

Integer parentWindowId : 부모 윈도우의 ID.
Function callback : 아래와 같은 형식의 콜백함수
function (Object result) {
// result.popupId : 팝업으로 복원된 윈도우의 ID
// result.tabId : 사이드바 탭의 ID
}
이러한 콜백함수의 매개변수는 v3.26.244.14 이상의 버전에서 사용할 수 있습니다.

팝업으로 복원된 윈도우의 ID는 새로 부여된 ID입니다. whale.sidebarAction.dock()으로 붙일 때 사용했던 윈도우 ID와는 다르다는 것을 주의해야 합니다.
/**
* @deprecated
*/
function (Integer windowId, Integer tabId) { ... }
// 팝업으로 복원된 윈도우의 ID, 탭으로 복원되는 경우 윈도우 ID와 탭 ID가 모두 넘어옵니다.
이 형식의 매개변수는v3.26.244.14에서 삭제deprecated되었습니다. 단, 하위 버전의 브라우저에서 확장앱을 사용하는 경우 여전히 콜백함수가 이러한 방식으로 동작할 수 있으므로, 호환성을 고려한 대응이 필요할 수 있습니다.

반환값

Promise<object>: 프로미스는 Manifest V3 이상에서 지원되며, 이전 버전과의 호환성을 위해 콜백함수 또한 제공됩니다. 함수 호출 시 프로미스와 콜백함수를 동시에 사용할 수는 없습니다. 프로미스가 이행된resolved 결과값은 콜백함수의 매개변수와 동일한 형식입니다.

이벤트

onClicked

사이드바 확장앱 아이콘이 클릭될 때 발생하는 이벤트 핸들러를 등록합니다.

whale.sidebarAction.onClicked.addListener(Function callback);

인자

Function callback : 아래와 같은 형식의 콜백함수

function (Object result) {
   // result.windowId
   // result.opened : 사이드바 영역이 열렸으면 true, 닫혔으면 false.
}

자료형

웹 API

최신 웹 환경에서는 HTML, JavaScript 등 표준 웹 기술만으로도 훌륭한 웹 어플리케이션을 개발할 수 있습니다. 푸시 알림, 웹 저장소 등 많은 기술들이 이미 표준 HTML5 규격으로 확장앱 기술의 도움 없이도 활용할 수 있습니다. 여기에 더해 네이버 웨일은 사이드바, 스페이스, 모바일창 등 웨일만의 독특한 기능들도 표준 웹 기술 규격과 호환되는 형태로 활용할 수 있도록 웹 API를 제공합니다.

웹 서비스 개발시 웨일 브라우저 사용자에게 새로운 경험을 제공해 줄 수 있고, 확장앱과 함께 활용하면 또 다른 가능성을 찾을 수 있습니다.
네이버 웨일이 제공하는 확장 웹 API를 확인해보세요.

네이버 웨일 버전에 따라 지원 범위가 다를 수 있습니다.

창 열기

네이버 웨일은 일반적인 브라우저 창과 탭 외에 사이드바, 스페이스 및 모바일창 등 다양한 웹 뷰 영역을 제공합니다.
이 영역들을 확장앱 API 를 사용하지 않아도 HTML 및 JavaScript 코드로 활용할 수 있습니다.

웨일 2.0 이후 버전부터 사용할 수 있는 기능입니다.

rel 속성

HTML 규격에서 rel 속성은 현재 문서와 대상 문서의 관계를 정의하는 속성으로 <a>, <area>, <link> 요소에 사용할 수 있습니다. <a>, <area> 와 같은 링크 요소에 사용할 경우 어떤 종류의 링크를 만들 것인지를 제어하는 역할을 합니다. 이 속성에는 널리 알려져있는 noopener, noreferer 를 포함하여 다양한 링크 형식을 설정할 수 있습니다. 웨일에서는 표준 링크 형식 외에도 아래 값을 지정하여 웨일만의 기능을 활용할 수 있습니다.




링크 형식
설명
사용할 수 있는 요소
사용할 수 없는 요소




whale-sidebar


  링크를 사이드바 가변 패널로 엽니다
  
    target 속성과 함께 사용하면 둘 이상의 가변 패널을 생성할 수 있습니다.
    target 속성을 지정하지 않거나 target="_blank"로 지정한 경우 새로운 패널을 열지 않고 이미 열려있는 패널을 재사용합니다.
  


<a>,<area>
<link>


whale-space


  링크를 웨일 스페이스에 엽니다. 이미 웨일 스페이스에 다른 페이지가 열려있는 경우 같은 영역을 재사용하여 페이지를 이동합니다.
  스페이스 연결 끊기로 분리된 상태에서도 동일한 규칙으로 동작합니다.


<a>,<area>
<link>


whale-mobile

  
    링크를 새 모바일창으로 엽니다.
    target 속성과 상관없이 항상 새 창으로 열립니다.
  

<a>,<area>
<link>


web-app

  링크를 웹 앱창으로 엽니다.
  
    웹 앱창은 일반 창 혹은 모바일창과 구별되는 인터페이스를 제공합니다. 항상 위에 표시, 투명도 조절 등의 기능을 갖습니다.
    링크(대상) 페이지에 Web App Manifest가 정의되어 있는 경우 웹 앱 설치를 유도하는 인터페이스가 표시됩니다.
    Manifest 가 정의되어 있지 않은 보통의 웹 페이지인 경우 바로가기 앱(Shortcut App)으로 설치를 유도합니다.
    
  

<a>,<area>
<link>

링크 형식	설명	사용할 수 있는 요소	사용할 수 없는 요소
`whale-sidebar`	링크를 사이드바 가변 패널로 엽니다 `target` 속성과 함께 사용하면 둘 이상의 가변 패널을 생성할 수 있습니다. `target` 속성을 지정하지 않거나 `target="_blank"`로 지정한 경우 새로운 패널을 열지 않고 이미 열려있는 패널을 재사용합니다.	`<a>`,`<area>`	`<link>`
`whale-space`	링크를 웨일 스페이스에 엽니다. 이미 웨일 스페이스에 다른 페이지가 열려있는 경우 같은 영역을 재사용하여 페이지를 이동합니다. 스페이스 연결 끊기로 분리된 상태에서도 동일한 규칙으로 동작합니다.	`<a>`,`<area>`	`<link>`
`whale-mobile`	링크를 새 모바일창으로 엽니다. `target` 속성과 상관없이 항상 새 창으로 열립니다.	`<a>`,`<area>`	`<link>`
`web-app`	링크를 웹 앱창으로 엽니다. 웹 앱창은 일반 창 혹은 모바일창과 구별되는 인터페이스를 제공합니다. 항상 위에 표시, 투명도 조절 등의 기능을 갖습니다. 링크(대상) 페이지에 Web App Manifest가 정의되어 있는 경우 웹 앱 설치를 유도하는 인터페이스가 표시됩니다. Manifest 가 정의되어 있지 않은 보통의 웹 페이지인 경우 바로가기 앱(Shortcut App)으로 설치를 유도합니다.	`<a>`,`<area>`	`<link>`

웨일에서 제공하는 링크 형식들이 결국 링크를 표시할 대상을 가리키고 있다는 점에서 “왜 target 속성을 사용하지 않는가?” 라는 의문을 가질 수 있습니다. target 속성을 확장하면 해당 링크 요소는 웨일 이외의 브라우저에서 새 창 열기로 동작하므로 표준 웹 규격에서 기대하는 동작을 해칠 수 있습니다. 현대 HTML 표준 규격에서도 rel 속성은 링크 요소의 기능을 설정한다고 정의하고 있는 만큼 웹 표준과 호환성을 고려할 때 target이 아닌 rel 속성을 확장하는 것이 적합합니다.

HTML

<a>, <area> 요소에 rel 속성에 위 링크 형식 중 하나를 추가하여 사용할 수 있습니다.
rel 속성은 noopener, noreferrer 등 표준 규격에 포함된 다른 링크 형식과 함께 사용할 수 있습니다.
<a href="https://mail.naver.com/" rel="whale-sidebar noopener noreferrer">네이버 메일</a>
rel 속성에 사용한 확장 링크 형식이 whale-space, whale-mobile, web-app 중 하나인 경우
같은 요소에 정의한 target 속성은 무시됩니다.

rel 속성에 확장 링크 형식을 중복하여 사용한 경우 우선 순위는 whale-space > whale-sidebar > whale-mobile > web-app 순입니다. 우선되는 링크 형식을 함께 사용한 경우 후순위 링크 형식은 무시됩니다.

<a href="https://mail.naver.com/" rel="whale-sidebar whale-mobile">이 링크는 사이드바에서 열립니다</a>
<a href="https://mail.naver.com/" rel="whale-space whale-sidebar">이 링크는 스페이스에서 열립니다</a>

JavaScript

window.open() 메소드의 세 번째 인자에 추가하여 같은 효과를 얻을 수 있습니다.
이 경우 세 번째 인자에 추가할 수 있는 다른 설정들은 함께 지정하더라도 무시됩니다.
다만, 웹 앱 열기시에는 width, height 등 일부 설정은 함께 지정할 수 있습니다.

사이드바에서 열기

<a href="https://mail.naver.com/" rel="whale-sidebar">네이버 메일</a>

window.open('https://mail.naver.com/', '_blank', 'whale-sidebar');

스페이스에서 열기

<a href="https://shopping.naver.com/" rel="whale-space">네이버 쇼핑</a>

window.open('https://shopping.naver.com/', '_blank', 'whale-space');

모바일창에서 열기

<a href="https://m.naver.com/" rel="whale-mobile">네이버</a>

window.open('https://m.naver.com/', '_blank', 'whale-mobile');

웹 앱 열기

<a href="https://twitter.com/" rel="web-app">twitter.com</a>

window.open('https://twitter.com/', '_blank', 'web-app');

브라우저API

확장앱 API

호환성

제약사항

매니페스트

최소 매니페스트

콘텐츠 스크립트 등록

매니페스트 키

manifest_version

name

version

description

icons

action

background

chrome_settings_overrides

chrome_url_overrides

commands

content_scripts

content_security_policy

cross_origin_embedder_policy

cross_origin_opener_policy

declarative_net_request

default_locale

devtools_page

export

externally_connectable

homepage_url

host_permissions

import

incognito

minimum_whale_version

omnibox

optional_host_permissions

optional_permissions

options_page

options_ui

permissions

requirements

sandbox

short_name

sidebar_action

storage

tts_engine

update_url

version_name

web_accessible_resources

whale.sidebarAction

매니페스트

메소드

show

인자

hide

인자

setTitle

인자

getTitle

인자

setIcon

인자

setPage

인자

getPage

인자

setBadgeText

인자

getBadgeText

인자

setBadgeBackgroundColor

인자

getBadgeBackgroundColor

인자

dock

인자

undock

인자

반환값

이벤트

onClicked

인자