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 navigates to the page first, waits for the final URL after any HTTP redirects and client-side JavaScript redirects (up to 5 seconds), derives the domain automatically, injects the cookies, and reloads. This handles sites that redirect from http:// to https://, from a root domain to a subdomain, or via client-side JS (e.g. bbc.com redirecting to bbc.co.uk).

var pdf = await renderer
    .AddCookie("ckns_policy", "111")    // domain inferred from final URL
    .AddCookie("session", "tok_xyz")    // domain inferred from final URL
    .RenderUrlAsPdfAsync("https://bbc.co.uk");

Note

Domain inference requires two navigations (one to discover the final URL, one to render with cookies). Use explicit domains when possible for best performance.

Tip

CobaltPdf automatically derives the registrable domain (eTLD+1) from the final URL. This means international domains like co.uk, com.au, co.jp, and many others are handled correctly — a cookie set for www.bbc.co.uk will be scoped to .bbc.co.uk, not .co.uk.

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