Sessions and Site Data

Store browsing data across Views, isolate profiles, and configure in-memory or persistent sessions.

A Session stores a View's browsing data, including cookies, local storage, IndexedDB databases, and cached resources.

You can choose between temporary (in-memory) sessions or persistent (on-disk) sessions, and decide whether Views share sessions or run in isolation.

📘 Sessions in AppCore

In AppCore, App::Create() manages sessions for you, writing to an OS app-data folder by default. You can change the session path by specifying Config::cache_path.

#Using the Default Session

To assign the default session to a new View, pass nullptr for the session parameter.

///
/// Passing nullptr for the Session gives this View the default session.
///
RefPtr<View> view = renderer->CreateView(800, 600, ViewConfig(), nullptr);

The renderer creates this session automatically during Renderer::Create(). It is a persistent session named default, and most applications do not need any other session.

You can also retrieve it directly by calling Renderer::default_session().

#Choosing Session Persistence

Call Renderer::CreateSession() to create a session, then pass it to Renderer::CreateView() (see Creating Views).

A View keeps its assigned session alive, so you don't need to store the RefPtr<Session>.

#Creating an In-Memory Session

To create a session that stores all site data in memory, pass false for is_persistent.

///
/// A private session: nothing it stores is written to disk.
///
RefPtr<Session> incognito = renderer->CreateSession(false, "incognito");
RefPtr<View> view = renderer->CreateView(800, 600, ViewConfig(), incognito);

An in-memory session never writes cookies, local storage, or IndexedDB databases to disk. When the session is destroyed or the application exits, all browsing data is discarded.

Use in-memory sessions for private browsing views, guest logins, or kiosk interfaces that must discard state when finished.

#Creating a Persistent Session

To create a session that saves its data to disk, pass true for is_persistent.

///
/// Player two's cookies and storage live apart from the default session.
///
RefPtr<Session> player_two = renderer->CreateSession(true, "player-2");
RefPtr<View> view = renderer->CreateView(800, 600, ViewConfig(), player_two);

Persistent sessions write browsing data to disk under the session name. Creating a persistent session with the same name on the next launch reloads that data, restoring saved logins and settings.

Use persistent sessions to give individual users or players their own isolated profiles alongside the default session.

#Configuring the Storage Path

To set the base directory where persistent sessions write their data, configure Config::cache_path before creating the renderer.

void Init() {
  InitPlatform();

  Config config;
  config.cache_path = "./ultralight_cache/";
  Platform::instance().set_config(config);

  ///
  /// The default session writes to ./ultralight_cache/default/ and a
  /// "player-2" session to ./ultralight_cache/player-2/.
  ///
  renderer = Renderer::Create();
}

Each persistent session writes to a subfolder inside Config::cache_path matching the session name. You should set this path to a writable, per-user folder (see Creating the Renderer).

Call Session::disk_path() to inspect the folder where a persistent session writes its data. This returns Config::cache_path joined with the session name (relative when Config::cache_path is relative). This path is meaningful only for persistent sessions.

🚧 Set Cache Path Explicitly

If you leave Config::cache_path empty, the renderer creates the default directory relative to the current working directory of the process. Site data lands wherever the application was launched from.

#Sharing Sessions

You can share browsing data across multiple Views by assigning them the same session.

#Sharing Between Views

To share browsing data, pass the same Session to each Renderer::CreateView() call:

RefPtr<View> lobby_view;
RefPtr<View> shop_view;

void CreatePlayerTwoViews() {
  RefPtr<Session> player_two = renderer->CreateSession(true, "player-2");

  ///
  /// Both Views share player two's cookies and storage.
  ///
  lobby_view = renderer->CreateView(800, 600, ViewConfig(), player_two);
  shop_view = renderer->CreateView(800, 600, ViewConfig(), player_two);
}

Views on the same session share cookies, local storage, IndexedDB databases, and cached resources— logging in on one View logs in to all other Views on that session.

Each View keeps its own session storage and back/forward history.

Views assigned to differently named sessions keep their data isolated.

#Reusing Persistent Session Names

Two persistent sessions created with the same name share one disk folder and its stored data. The library does not check whether session names are unique.

In-memory sessions never share data. Separate in-memory sessions remain isolated from each other, and an in-memory session never reads a persistent session's data, even if both use the same name.

🚧 Use Unique Session Names

Give each persistent session its own name unless sharing data is intentional. Persistent sessions with the same name share their data live while the application runs and reload it across launches.