Skip to content

Cookie functions#

These functions read, add and delete the cookies of the browser the script runs in (in 9Login, the profile's cookies) for every site, including HttpOnly cookies that document.cookie cannot see. You can use them in 9Login scripts and when you test in Studio. In 9Hits campaign macros, every function on this page is blocked and returns {error: "Blocked"}.

Warning

Cookies keep the profile signed in to websites: anyone who has them can use those accounts, so keep files of saved cookies private. ClearCookies signs the profile out of every site and cannot be undone.

The functions on this page are asynchronous, so call them with await. Expiry times are in seconds since 1970, not milliseconds: Math.floor(Date.now() / 1000) + 86400 is one day from now. To view or edit cookies by hand while the profile is stopped, use the Cookies box of 9Login.

GetCookies #

Lists the cookies of the profile, all of them or only those that match a filter. Use it to save a login to a file, or to find the exact domain of a cookie before deleting it.

Syntax 
await GetCookies(filter=null);
Parameters
Name Description
filter Optional object with any of these fields: url (the cookies the browser would send to this address), domain (cookies of this domain and its subdomains), name, path (exact match), secure (true or false), session (true or false). Fields that are empty strings are ignored. Left out, the function returns every cookie of the profile, for all sites.
Returns

An array of cookies; an empty array when nothing matches or the read fails. Each cookie is an object with these fields:

Field Meaning
name, value Name and value of the cookie.
domain Domain of the cookie. A leading dot (.example.com) means it is also sent to every subdomain.
hostOnly true when the cookie belongs to one exact host only.
path Path of the cookie, for example /.
secure true when the cookie is sent over HTTPS only.
httpOnly true when the page's JavaScript cannot read the cookie.
sameSite "no_restriction", "lax", "strict" or "unspecified".
session true for a session cookie, which has no expiry time.
expirationDate Expiry time in seconds since 1970. Absent on a session cookie.

Cookies created with the Partitioned attribute (usually by a third-party iframe) are not listed.

Example 
1
2
3
4
5
// save the cookies of one site to a file
const cookies = await GetCookies({domain: "example.com"});
const w = WriteFile("C:/data/cookies/example.json", JSON.stringify(cookies));
if (w.error) Log("Save failed:", w.error);
else Log(cookies.length, "cookies saved");

GetCookie #

Reads one cookie by name: the one the browser would send to a given address. Use it, for example, to check whether the profile is still signed in to a site.

Syntax 
await GetCookie(name, url);
Parameters
Name Description
name Exact name of the cookie.
url Full address including the scheme, for example "https://example.com/". A bare "example.com" does not work.
Returns

The cookie, as an object with the same fields as in GetCookies. null when there is no such cookie, or when name or url is missing or invalid. When several cookies with that name match the address, the one with the longest path is returned.

Example 
1
2
3
4
// stop early if the profile is not signed in
const c = await GetCookie("session_id", "https://example.com/");
if (!c) return "not signed in";
if (!c.session) Log("Login expires at", new Date(c.expirationDate * 1000).toISOString());

SetCookie #

Creates a cookie, or overwrites the one with the same name, domain and path. Use it to restore a login saved with GetCookies: each cookie of that list can be passed back as it is.

Syntax 
await SetCookie(cookie);
Parameters
Name Description
cookie Object describing the cookie, with the fields below.
Field Meaning
name Required.
value Required; may be "".
url Address the cookie belongs to, for example "https://example.com/". Can be left out when domain is given.
domain With a leading dot (".example.com"), the cookie covers every subdomain. For a cookie of one exact host, give url and no domain, or set hostOnly: true.
path Path of the cookie, for example "/". Left out, it is taken from url.
secure true: the cookie is sent over HTTPS only.
httpOnly true: the page's JavaScript cannot read the cookie.
sameSite "no_restriction", "lax", "strict" or "unspecified"; other values are ignored. "no_restriction" requires secure: true.
expirationDate Expiry time in seconds since 1970 (expires also works). Left out, 0 or negative: a session cookie. An expiry more than 400 days ahead is cut to 400 days.
Returns

true when the cookie was stored; false when name, value or the address (url or domain) is missing, or when the browser refuses the cookie.

Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// restore the cookies saved with GetCookies, then open the site
const r = ReadFileAsString("C:/data/cookies/example.json");
if (r.error) return r.error;
for (const c of JSON.parse(r.result)) {
    if (!(await SetCookie(c))) Log("Refused:", c.name);
}
await Navigate("https://example.com/");

// a new cookie that lasts 7 days
await SetCookie({
    url: "https://example.com/",
    name: "lang",
    value: "en",
    expirationDate: Math.floor(Date.now() / 1000) + 7 * 86400,
});

DeleteCookies #

Deletes the cookies with a given name on one domain. Other sites are not touched.

Syntax 
await DeleteCookies(name, domain="", url="");
Parameters
Name Description
name Exact name of the cookie.
domain Domain written exactly as GetCookies reports it: ".example.com" (with the dot) for a cookie that covers subdomains, "example.com" for a cookie of that host only. Subdomains do not match: "example.com" does not delete a .example.com or www.example.com cookie.
url Used only when domain is left out: the host of this http or https address stands in for domain, so only cookies of that exact host are deleted.
Returns

true when the request went through, even when no cookie matched; false when name is missing, when both domain and url are missing, or on error. To be sure a cookie is gone, check with GetCookie or GetCookies.

Example 
1
2
3
// delete every "session_id" cookie of a site, whatever its exact domain
const cookies = await GetCookies({domain: "example.com", name: "session_id"});
for (const c of cookies) await DeleteCookies(c.name, c.domain);

ClearCookies #

Deletes every cookie of the profile, for every site, so the profile is signed out everywhere. Local storage and the cache are kept. To clear one site only, use GetCookies and DeleteCookies.

Syntax 
await ClearCookies();
Returns

true on success, false on error.

Example 
1
2
3
4
// start again from the login page with no cookies
await ClearCookies();
await Navigate("https://example.com/login");
await WaitForLoading(30);