Skip to content

Session ​

Session represents a storage partition: cookies, localStorage, IndexedDB, caches, and other data left by web pages in a WebView are all stored in some partition. Through Session, the app can read and write the partition's cookies, and clear the data in it.

Each partition is a separate set of data. Web pages in the same partition share data: sign in on one page, and another page in the same partition is signed in too. Different partitions can't see each other's data. Which partition a page uses is set with webPreferences.partition when the WebView is created, and can't be changed afterward. For how to write partition names, see Partitions.

This group has two more types:

  • Cookies: a partition's cookies, obtained from the cookies property.
  • Cookie: each record you get when reading cookies.

Inheritance: Session does not inherit from any class.

For how to set up sign-in state before opening a page, clear data on sign-out, and keep multiple accounts separate, see the guide Managing web page sign-in state.

Constructor ​

It can't be created with new: new Session() throws TypeError: Illegal constructor: Session is created by the runtime, not by new.

There are two ways to get a Session; the same partition gives the same object either way:

A Session object exists from its first use until the app exits. You can store it anywhere, or get it again each time you use it.

Static properties ​

The global object session needs no creating and is available at any time.

session.defaultSession read-only

The default partition. Shared by all web pages that don't specify partition.

Static methods ​

session.fromPartition()

Gets a partition by name. Partition names are written the same way as webPreferences.partition.

Instance properties ​

PropertyDescription
cookies read-onlyThis partition's cookies

Instance methods ​

MethodDescription
isPersistent()Whether this partition's data survives an app restart
clearStorageData()Clears data in this partition; can be limited to certain kinds or to one site

Partitions ​

Written asWhich dataUsed byAfter an app restart
session.defaultSessionThe default setAll web pages that don't specify partitionData is kept
session.fromPartition('persist:name')The set for that nameWeb pages whose partition is the same nameData is kept
session.fromPartition('name') (without persist:)The set for that name, in memory onlyWeb pages whose partition is the same nameData is gone
  • session.fromPartition('') and session.fromPartition('persist:') are both session.defaultSession.
  • In partitions whose "data is kept", cookies without an expiration date are the exception: they are gone after the app restarts; see Session cookies.
  • A partition's data belongs to this app only. Other apps and Safari can't read it (per the iOS definition; not verified in the simulator).
  • After the app launches, the first read or write of a partition takes 0.6 to 1 second; after that each takes under 1 millisecond (measured). This is an asynchronous wait; the interface stays responsive meanwhile.

Note: Cookies in a partition belong to web pages only. fetch has its own set of cookies, and the two aren't connected: cookies written here aren't sent with fetch requests, and clearing data here doesn't clear fetch's cookies.

Examples ​

Setting up sign-in state before opening a page ​

Starting from a blank app: write a cookie first, then open the page, and the page's requests carry it.

js
application.addEventListener('sceneconnect', async (e) => {
  const win = new UIWindow(e.scene);
  const page = new UIViewController();
  page.view.backgroundColor = 'systemBackground';
  win.rootViewController = page;
  win.makeKeyAndVisible();

  const cookies = session.defaultSession.cookies;
  await cookies.set({
    url: 'https://httpbin.org/',
    name: 'token',
    value: 'abc123',
    httpOnly: true,
    expirationDate: Date.now() / 1000 + 7 * 24 * 3600,
  });

  const web = new WebView();
  web.frame = page.view.bounds;
  page.view.addSubview(web);
  await web.webContents.loadURL('https://httpbin.org/cookies');

  const list = await cookies.get({ url: 'https://httpbin.org/' });
  console.log(list.map((c) => c.name + '=' + c.value).join('; '));
});

Effect

  • The web page on screen shows { "cookies": { "token": "abc123" } }. This URL echoes the cookies sent with the request, which shows the page's request carried it.
  • The console prints token=abc123.
  • This cookie is set httpOnly, so a script in the page reading document.cookie gets an empty string.
  • It has an expiration date (7 days later), so it survives an app restart.

Signing out ​

js
await session.defaultSession.clearStorageData();

Effect: All cookies, localStorage, and caches in the default partition are cleared. Pages already open send their next requests without cookies.

Differences from Electron ​

ElectronHereDifference
require('electron').sessionThe global sessionNo import needed
session.defaultSession, session.fromPartition(partition)Same
contents.sessionSame
ses.cookiesSameSee Cookies
ses.clearStorageData({ origin, storages })Sameorigin is matched by domain only, regardless of scheme and port
ses.isPersistent()Same

Corresponding iOS API ​

ObjCJS
WKWebsiteDataStore.defaultDataStoresession.defaultSession
[WKWebsiteDataStore dataStoreForIdentifier:], nonPersistentDataStoresession.fromPartition(partition)
webView.configuration.websiteDataStorewebView.webContents.session
dataStore.httpCookieStoreses.cookies
dataStore.isPersistentses.isPersistent()
[dataStore removeDataOfTypes:modifiedSince:completionHandler:]ses.clearStorageData({ storages })
[dataStore fetchDataRecordsOfTypes:…] plus removeDataOfTypes:forDataRecords:…ses.clearStorageData({ origin })

See also ​

  • Managing web page sign-in state: writing sign-in cookies, signing out, multiple accounts, reading cookies after the page signs in
  • Cookies: reading, writing, and deleting cookies; notifications when cookies change
  • Cookie: the fields each cookie you read has
  • WebView: use partition when creating a page to choose its partition; webContents.session gets the corresponding Session
  • fetch: its cookies are a separate set, not connected to these