Cookies & Storage

CobaltPdf supports two mechanisms for pre-loading browser state before the page renders: cookies and web storage (localStorage / sessionStorage). Both are injected per-render and are fully isolated from other concurrent renders.

Cookies

With a Known Domain

When you know the target domain upfront, provide it explicitly. The cookie is injected before navigation and is present on the very first request — including any server-side rendering that happens before JavaScript runs.

var pdf = await renderer
    .AddCookie("session_id", "abc123", ".example.com")
    .AddCookie("user_prefs", "dark_mode=1", ".example.com", "/settings")
    .RenderUrlAsPdfAsync("https://example.com/dashboard");

The domain parameter follows browser cookie conventions — a leading dot (.example.com) makes the cookie available to all subdomains.

With an Auto-Inferred Domain

If you omit the domain, CobaltPdf scopes the cookie to the registrable domain (eTLD+1) of the target URL and commits it to the cookie jar before navigation — so it is present on the very first request, with no reload. It also re-asserts the cookie at document-start in every document the render touches, including the page reached after a client-side JavaScript redirect (e.g. www.bbc.com redirecting to www.bbc.co.uk). So a cookie-gated consent banner is dismissed on the redirected domain without a second navigation.

var pdf = await renderer
    .AddCookie("ckns_explicit", "1")    // domain inferred — no reload
    .RenderUrlAsPdfAsync("https://www.bbc.com");

Tip

CobaltPdf derives the registrable domain (eTLD+1), so international domains like co.uk, com.au, and co.jp are handled correctly — a cookie for www.bbc.co.uk is scoped to .bbc.co.uk, not .co.uk.

Note

When the host is localhost, an IP address (e.g. 127.0.0.1), or a single-label intranet hostname (e.g. my-server), no registrable domain exists — the cookie is registered as a host-only cookie instead, matching the exact host only.

AddCookie accepts name, value, an optional domain, and an optional path (defaults to /). Additional properties can be set on CobaltCookie directly when constructing a full options object:

Property	Type	Default	Description
`Name`	`string`	required	Cookie name
`Value`	`string`	required	Cookie value
`Domain`	`string?`	`null`	Domain scope. `null` = auto-infer
`Path`	`string?`	`"/"`	URL path scope
`Expires`	`DateTime?`	`null`	Expiry time. `null` = session cookie
`Secure`	`bool`	`true`	Restrict to HTTPS
`HttpOnly`	`bool`	`false`	Inaccessible to JavaScript

Multiple Cookies

Chain multiple AddCookie calls — there is no limit:

var pdf = await renderer
    .AddCookie("auth",    "Bearer eyJhbGci...", ".api.example.com")
    .AddCookie("locale",  "en-GB",              ".example.com")
    .AddCookie("consent", "1",                  ".example.com")
    .RenderUrlAsPdfAsync("https://app.example.com/report");

Web Storage

localStorage and sessionStorage values are injected as an init script — they are set before any page script runs, so the page sees them as if they were already present.

localStorage

var pdf = await renderer
    .AddLocalStorage("authToken",    "eyJhbGci...")
    .AddLocalStorage("userId",       "42")
    .AddLocalStorage("featureFlags", "{\"darkMode\":true}")
    .RenderUrlAsPdfAsync("https://example.com/dashboard");

sessionStorage

var pdf = await renderer
    .AddSessionStorage("cart",          "[{\"id\":1,\"qty\":2}]")
    .AddSessionStorage("checkoutStep",  "3")
    .RenderUrlAsPdfAsync("https://example.com/checkout");

Combining Cookies and Storage

Cookies and storage can be freely combined in a single render:

var pdf = await renderer
    .AddCookie("session", "abc123", ".example.com")
    .AddLocalStorage("authToken", "eyJhbGci...")
    .AddSessionStorage("currentUser", "{\"id\":42,\"name\":\"Alice\"}")
    .RenderUrlAsPdfAsync("https://example.com/account");

HTTP Headers & User-Agent

CobaltPdf can override the browser's User-Agent and inject custom HTTP request headers. See the dedicated HTTP Headers & User-Agent article for full details and examples.

Quick example:

var pdf = await renderer
    .WithUserAgent("ReportingService/2.0")
    .WithHttpHeader("Authorization", "Bearer eyJhbGci...")
    .AddCookie("session", "abc123", ".example.com")
    .AddLocalStorage("theme", "dark")
    .RenderUrlAsPdfAsync("https://example.com/dashboard");

Content Security Policy

Some sites block inline script injection with a strict CSP. If your storage values are not being picked up, enable the bypass flag:

var pdf = await renderer
    .WithCspBypass()
    .AddLocalStorage("token", "abc")
    .RenderUrlAsPdfAsync("https://strict-csp-site.com");

Table of Contents