Session

The browsing session shared by every browser in the application.

Cookies, caches, and other browsing data live in the session, so everything loaded by any BrowserView shares them.

import { session } from '@mobrowser/api';

Example 

import { session } from '@mobrowser/api';

console.log(session.storagePath)

Properties 

storagePath 

readonly storagePath: string;

The directory the session keeps its browsing data in, as an absolute path.

Cookies, caches, local storage, and the rest of the browsing data are stored under this directory. It is created when the application first starts, and its contents are not part of the public API — treat the path as a location to inspect or back up, not as a file layout to depend on.

Example 

import { session } from '@mobrowser/api';

console.log(`Browsing data lives in ${session.storagePath}`)

cookies 

readonly cookies: Cookies;

The cookie store of the session.

Example 

import { session } from '@mobrowser/api';

const cookies = await session.cookies.get({ url: 'https://example.com' })
console.log(`${cookies.length} cookies for example.com`)

userAgent 

readonly userAgent: string;

The user agent the session identifies itself with.

This is the string setUserAgent() was last given, or the one Chromium derives from its version and the platform when the application has not replaced it.

Example 

import { session } from '@mobrowser/api';

console.log(session.userAgent)

Methods 

isPersistent() 

isPersistent(): boolean;

Checks whether the session writes browsing data to disk.

A persistent session keeps cookies, caches, and local storage across restarts. A non-persistent session holds them in memory only and discards them when the application quits.

Return value 

True if the session writes browsing data to disk, false otherwise.

Example 

import { session } from '@mobrowser/api';

if (!session.isPersistent()) {
  console.log('Browsing data will be discarded on quit')
}

setUserAgent() 

setUserAgent(userAgent: string): void;

Replaces the user agent the session identifies itself with.

The new user agent reaches the pages that are already open as well as the ones loaded afterwards, but a page that has already loaded keeps reporting the previous value from navigator.userAgent until it navigates again.

@throws TypeError if userAgent is missing, empty, or not a string.

Example 

import { session } from '@mobrowser/api';

session.setUserAgent('MyApp/1.0')

getCacheSize() 

getCacheSize(): Promise<number>;

Measures how much disk space the HTTP cache is using.

Return value 

The size of the cache in bytes, as a promise. The figure is an estimate and may be an upper bound.

Example 

import { session } from '@mobrowser/api';

const bytes = await session.getCacheSize()
console.log(`The cache is using ${Math.round(bytes / 1e6)} MB`)

clearCache() 

clearCache(): Promise<void>;

Empties the HTTP cache.

Cookies, local storage, and the other browsing data are left alone. Use clearData() to remove those as well.

Return value 

A promise that resolves once the cache has been emptied.

Example 

import { session } from '@mobrowser/api';

await session.clearCache()

clearData() 

clearData(options?: ClearDataOptions): Promise<void>;

Removes browsing data.

Called with no options, it removes every kind of browsing data, for every site, of every age.

Return value 

A promise that resolves once the data has been removed. It is rejected when some of the data could not be removed. @throws TypeError if options is not an object, if one of its fields has the wrong type, if dataTypes names an unknown type, if an origin is not a valid URL, or if both origins and excludeOrigins are given.

Example 

import { session } from '@mobrowser/api';

// Sign the user out of one site.
await session.clearData({
  dataTypes: ['cookies', 'storage'],
  origins: ['https://example.com']
})

// Clear everything from the last hour.
await session.clearData({ since: Date.now() / 1000 - 3600 })

clearAuthCache() 

clearAuthCache(): Promise<void>;

Forgets the credentials the application has cached for HTTP authentication.

A site that asked for credentials earlier in the run asks again after this, which is what makes it the way to sign a user out of a site that uses HTTP authentication.

Return value 

A promise that resolves once the cached credentials are gone.

Example 

import { session } from '@mobrowser/api';

await session.clearAuthCache()

clearHostResolverCache() 

clearHostResolverCache(): Promise<void>;

Empties the cache of resolved host names.

The next request to each host resolves it again, which is what makes this useful after the machine changes network or its DNS records change.

Return value 

A promise that resolves once the cache has been emptied.

Example 

import { session } from '@mobrowser/api';

await session.clearHostResolverCache()

clearCodeCaches() 

clearCodeCaches(options?: ClearCodeCachesOptions): Promise<void>;

Drops the compiled code the engine has cached for scripts and WebAssembly modules.

The code is compiled again the next time a page runs it, so this costs only the time to recompile. It is worth doing when an application has replaced scripts that its pages load from a custom scheme, where the usual HTTP cache validation does not apply.

Return value 

A promise that resolves once the caches have been dropped. @throws TypeError if options is not an object, if urls is not an array of strings, or if one of them is not a valid URL.

Example 

import { session } from '@mobrowser/api';

await session.clearCodeCaches({ urls: ['app://bundle/main.js'] })