Electron 문서1.4.1

Docs / API / session

session

브라우저 세션, 쿠키, 캐시, 프록시 설정 등을 관리합니다.

session 모듈은 새로운 Session 객체를 만드는데 사용할 수 있습니다.

또한 WebContents의 session 속성이나 session 모듈을 통해 현재 존재하는 페이지의 session에 접근할 수 있습니다.

const {session, BrowserWindow} = require('electron')

let win = new BrowserWindow({width: 800, height: 600})
win.loadURL('http://github.com')

let ses = win.webContents.session

Methods

session 모듈은 다음과 같은 메서드를 가지고 있습니다:

session.fromPartition(partition[, options])

Returns Session - partition 문자열로부터 만들어진 Session 인스턴스. 이미 partition에 해당하는 Session이 존재할 경우, 해당 세션이 반환됩니다. 그렇지않은 경우 Session 인스턴스가 options에 맞춰 새로 생성됩니다.

partition이 persist:로 시작하면 페이지는 지속성 세션을 사용하며 다른 모든 앱 내의 페이지에서 같은 partition을 사용할 수 있습니다. 만약 persist: 접두어로 시작하지 않으면 페이지는 인-메모리 세션을 사용합니다. partition을 지정하지 않으면 애플리케이션의 기본 세션이 반환됩니다.

options에 맞춰 Session을 생성하려면, partition에 해당하는 Session이 이미 이전에 사용되지 않고 있는지 확인해야 합니다. 이미 존재하는 Session 객체의 options를 변경하는 방법은 없습니다.

Properties

session 모듈은 다음과 같은 속성을 가지고 있습니다:

session.defaultSession

Session 객체, 애플리케이션의 기본 세션 객체.

Class: Session

세션의 속성을 가져오거나 설정합니다.

session 모듈을 사용하여 Session 객체를 생성할 수 있습니다:

const {session} = require('electron')
const ses = session.fromPartition('persist:name')
console.log(ses.getUserAgent())

Instance Events

Session 객체는 다음과 같은 이벤트를 가지고 있습니다:

Event: ‘will-download’

Electron의 webContents에서 item을 다운로드할 때 발생하는 이벤트입니다.

event.preventDefault() 메서드를 호출하면 다운로드를 취소하고, 프로세스의 다음 틱부터 item을 사용할 수 없게 됩니다.

const {session} = require('electron')
session.defaultSession.on('will-download', (event, item, webContents) => {
  event.preventDefault()
  require('request')(item.getURL(), (data) => {
    require('fs').writeFileSync('/somewhere', data)
  })
})

Instance Methods

Session 객체는 다음과 같은 메서드를 가지고 있습니다:

ses.getCacheSize(callback)

세션의 현재 캐시 크기를 반환합니다.

ses.clearCache(callback)

세션의 HTTP 캐시를 비웁니다.

ses.clearStorageData([options, callback])

웹 스토리지의 데이터를 비웁니다.

ses.flushStorageData()

디스크에 사용되지 않은 DOMStorage 데이터를 모두 덮어씌웁니다.

ses.setProxy(config, callback)

프록시 설정을 적용합니다.

pacScript와 proxyRules이 같이 제공되면 proxyRules 옵션은 무시되며 pacScript 컨픽만 적용됩니다.

proxyRules는 다음과 같은 규칙을 따릅니다:

proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]

예시:

proxyBypassRules는 밑에서 묘사된 규칙의 콤마로 구분된 목록입니다:

ses.resolveProxy(url, callback)

url의 프록시 정보를 해석합니다. callback은 요청이 수행되었을 때 callback(proxy) 형태로 호출됩니다.

ses.setDownloadPath(path)

다운로드 저장 위치를 지정합니다. 기본 다운로드 위치는 각 애플리케이션 데이터 디렉터리의 Downloads 폴더입니다.

ses.enableNetworkEmulation(options)

제공된 설정으로 session의 네트워크를 에뮬레이트합니다.

// 50kbps의 처리량과 함께 500ms의 레이턴시로 GPRS 연결을 에뮬레이트합니다.
window.webContents.session.enableNetworkEmulation({
  latency: 500,
  downloadThroughput: 6400,
  uploadThroughput: 6400
})

// 네트워크가 끊긴 상태를 에뮬레이트합니다.
window.webContents.session.enableNetworkEmulation({offline: true})

ses.disableNetworkEmulation()

활성화된 session의 에뮬레이션을 비활성화합니다. 기본 네트워크 설정으로 돌아갑니다.

ses.setCertificateVerifyProc(proc)

session에 인증서의 유효성을 확인하는 프로세스(proc)를 등록합니다. proc은 서버 인증서 유효성 검증 요청이 들어왔을 때 언제나 proc(hostname, certificate, callback) 형식으로 호출됩니다. callback(true)을 호출하면 인증을 승인하고 callback(false)를 호출하면 인증을 거부합니다.

setCertificateVerifyProc(null)을 호출하면 기본 검증 프로세스로 되돌립니다.

const {BrowserWindow} = require('electron')
let win = new BrowserWindow()

win.webContents.session.setCertificateVerifyProc((hostname, cert, callback) => {
  callback(hostname === 'github.com')
})

#### ses.setPermissionRequestHandler(handler)

session의 권한 요청에 응답을 하는데 사용하는 핸들러를 설정합니다. callback(true)를 호출하면 권한 제공을 허용하고 callback(false)를 호출하면 권한 제공을 거부합니다.

const {session} = require('electron')
session.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {
  if (webContents.getURL() === 'some-host' && permission === 'notifications') {
    return callback(false) // 거부됨.
  }

  callback(true)
})

ses.clearHostResolverCache([callback])

호스트 리소버(resolver) 캐시를 지웁니다.

ses.allowNTLMCredentialsForDomains(domains)

동적으로 HTTP NTML 또는 Negotiate 인증을 위해 언제나 자격 증명을 보낼지 여부를 설정합니다.

// 통합 인증을 위해 `example.com`, `foobar.com`, `baz`로 끝나는
// 모든 url을 지정합니다.
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')

// 통합 인증을 위해 모든 url을 지정합니다.
session.defaultSession.allowNTLMCredentialsForDomains('*')

ses.setUserAgent(userAgent[, acceptLanguages])

현재 세션에 대해 userAgent와 acceptLanguages를 덮어씁니다.

acceptLanguages는 반드시 쉼표로 구분된 순서에 맞춘 언어 코드의 리스트여야 하며 예를 들면 "en-US,fr,de,ko,zh-CN,ja" 입니다.

이는 현재 존재하는 WebContents에 적용되지 않으며 각 WebContents는 webContents.setUserAgent를 사용하여 세션 전체의 유저 에이전트를 덮어쓸 수 있습니다.

ses.getUserAgent()

Returns String - 현재 세션의 유저 에이전트.

ses.getBlobData(identifier, callback)

Returns Blob - identifier 에 연결된 blob 데이터.

Instance Properties

다음은 Session 인스턴스에서 사용할 수 있는 속성들입니다:

ses.cookies

현재 세션의 Cookies 객체.

ses.webRequest

현재 세션의 WebRequest 객체.

ses.protocol

현재 세션의 Protocol 객체 (protocol 모듈의 인스턴스).

const {app, session} = require('electron')
const path = require('path')

app.on('ready', function () {
  const protocol = session.fromPartition(partitionName).protocol
  protocol.registerFileProtocol('atom', function (request, callback) {
    var url = request.url.substr(7)
    callback({path: path.normalize(`${__dirname}/${url}`)})
  }, function (error) {
    if (error) console.error('Failed to register protocol')
  })
})

Class: Cookies

세션의 쿠키를 변경하거나 요청합니다.

Cookies 클래스의 인스턴스는 Session의 cookies 속성을 통해 접근합니다.

예를 들어:

// 모든 쿠키를 요청합니다.
session.defaultSession.cookies.get({}, (error, cookies) => {
  console.log(error, cookies)
})

// url에 관련된 쿠키를 모두 가져옵니다.
session.defaultSession.cookies.get({url: 'http://www.github.com'}, (error, cookies) => {
  console.log(error, cookies)
})

// 지정한 쿠키 데이터를 설정합니다.
// 동일한 쿠키가 있으면 해당 쿠키를 덮어씁니다.
const cookie = {url: 'http://www.github.com', name: 'dummy_name', value: 'dummy'}
session.defaultSession.cookies.set(cookie, (error) => {
  if (error) console.error(error)
})

Instance Events

다음은 Cookies 의 인스턴스의 이벤트입니다:

Event: ‘changed’

쿠키가 추가, 편집, 삭제, 만료되는 변경이 되면 발생합니다.

Instance Methods

다음은 Cookies 객체에서 사용할 수 있는 메서드들입니다:

ses.cookies.get(filter, callback)

details 객체에서 묘사한 모든 쿠키를 요청합니다. 모든 작업이 끝나면 callback이 callback(error, cookies) 형태로 호출됩니다.

cookies는 cookie 객체의 배열입니다.

ses.cookies.set(details, callback)

details 객체에 따라 쿠키를 설정합니다. 작업이 완료되면 callback이 callback(error) 형태로 호출됩니다.

ses.cookies.remove(url, name, callback)

url과 name에 일치하는 쿠키를 삭제합니다. 작업이 완료되면 callback이 callback() 형식으로 호출됩니다.

Class: WebRequest

생명주기 동안의 다양한 단계를 가지는 요청의 콘텐츠를 가로채고 변경합니다.

WebRequest 클래스의 인스턴스는 Session의 webRequest 속성을 통해 접근할 수 있습니다.

WebRequest의 메서드는 선택적인 filter와 listener 속성을 허용하며 listener는 API의 이벤트가 발생했을 때 listener(details) 형식으로 호출되고, details는 요청에 관한 내용을 표현하는 객체입니다. listener에 null을 전달하면 이벤트의 구독을 해제합니다.

filter는 urls 속성을 가진 객체입니다. 이 속성은 URL 규칙의 배열이며 URL 규칙에 일치하지 않는 요청을 모두 거르는데 사용됩니다. 만약 filter가 생략되면 모든 요청을 여과 없이 통과시킵니다.

어떤 listener의 이벤트들은 callback을 같이 전달하는데, 이벤트 처리시 listener의 작업을 완료한 후 response 객체를 포함하여 호출해야 합니다.

다음은 요청에 User-Agent 헤더를 추가하는 예시입니다:

// 다음 url에 대한 User Agent를 조작합니다.
const filter = {
  urls: ['https://*.github.com/*', '*://electron.github.io']
}

session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
  details.requestHeaders['User-Agent'] = 'MyAgent'
  callback({cancel: false, requestHeaders: details.requestHeaders})
})

Instance Methods

다음은 WebRequest 객체에서 사용할 수 있는 메서드들입니다:

webRequest.onBeforeRequest([filter, ]listener)

요청이 발생하면 listener가 listener(details, callback) 형태로 호출됩니다.

uploadData는 data 객체의 배열입니다:

callback은 response 객체와 함께 호출되어야 합니다:

webRequest.onBeforeSendHeaders([filter, ]listener)

HTTP 요청을 보내기 전 요청 헤더를 사용할 수 있을 때 listener가 listener(details, callback) 형태로 호출됩니다. 이 이벤트는 서버와의 TCP 연결이 완료된 후에 발생할 수도 있지만 http 데이터가 전송되기 전에 발생합니다.

callback은 response 객체와 함께 호출되어야 합니다:

webRequest.onSendHeaders([filter, ]listener)

서버에 요청이 전송되기 바로 전에 listener가 listener(details) 형태로 호출됩니다. 이전 onBeforeSendHeaders의 response와 다른점은 리스너가 호출되는 시간으로 볼 수 있습니다.

webRequest.onHeadersReceived([filter, ]listener)

요청의 HTTP 응답 헤더를 받았을 때 listener가 listener(details, callback) 형태로 호출됩니다.

callback은 response 객체와 함께 호출되어야 합니다:

webRequest.onResponseStarted([filter, ]listener)

요청 본문의 첫 번째 바이트를 받았을 때 listener가 listener(details) 형태로 호출됩니다. 이는 HTTP 요청에서 상태 줄과 요청 헤더가 사용 가능한 상태를 의미합니다.

webRequest.onBeforeRedirect([filter, ]listener)

서버에서 시작된 리다이렉트가 발생했을 때 listener가 listener(details) 형태로 호출됩니다.

webRequest.onCompleted([filter, ]listener)

요청이 완료되면 listener가 listener(details) 형태로 호출됩니다.

webRequest.onErrorOccurred([filter, ]listener)

에러가 발생하면 listener가 listener(details) 형태로 호출됩니다.

고쳐야 할 것이 있습니까? 소스에서 변경을 제안할 수 있습니다.
다른 버전의 문서가 필요한가요? 이전 버전 또는 커뮤니티 번역을 보세요.
모든 문서를 한번에 검색하고 싶으신가요? 한 페이지 문서를 보세요.