Session
Index
Constructors
constructor
Session configuration.
Parameters
options: SessionOptions
Returns Session
Properties
readonlyid
userData
Methods
getCookieString
Returns cookies saved with the session in the typical key1=value1; key2=value2 format, ready to be used in a cookie header or elsewhere.
Parameters
url: string
Returns string
Represents
Cookieheader.
getCookies
Returns cookies in a format compatible with puppeteer/playwright and ready to be used with
page.setCookie.Parameters
url: string
website url. Only cookies stored for this url will be returned
Returns Cookie[]
getState
Gets session state for persistence in KeyValueStore.
Returns SessionState
Represents session internal state.
isBlocked
Indicates whether the session is blocked. Session is blocked once it reaches the
maxErrorScore.Returns boolean
isExpired
Indicates whether the session is expired. Session expiration is determined by the
maxAgeSecs. Once the session is older thancreatedAt + maxAgeSecsthe session is considered expired.Returns boolean
isMaxUsageCountReached
Indicates whether the session is used maximum number of times. Session maximum usage count can be changed by
maxUsageCountparameter.Returns boolean
isUsable
Indicates whether the session can be used for next requests. Session is usable when it is not expired, not blocked and the maximum usage count has not be reached.
Returns boolean
markBad
Increases usage and error count. Should be used when the session has been used unsuccessfully. For example because of timeouts.
Returns void
markGood
This method should be called after a successful session usage. It increases
usageCountand potentially lowers theerrorScoreby theerrorScoreDecrement.Returns void
retire
Marks session as blocked and emits event on the
SessionPoolThis method should be used if the session usage was unsuccessful and you are sure that it is because of the session configuration and not any external matters. For example when server returns 403 status code. If the session does not work due to some external factors as server error such as 5XX you probably want to usemarkBadmethod.Returns void
retireOnBlockedStatusCodes
With certain status codes:
401,403or429we can be certain that the target website is blocking us. This function helps to do this conveniently by retiring the session when such code is received. Optionally the default status codes can be extended in the second parameter.Parameters
statusCode: number
HTTP status code.
Returns boolean
Whether the session was retired.
setCookie
Sets a cookie within this session for the specific URL.
Parameters
rawCookie: string
url: string
Returns void
setCookies
Saves an array with cookie objects to be used with the session. The objects should be in the format that Puppeteer uses, but you can also use this function to set cookies manually:
[
{ name: 'cookie1', value: 'my-cookie' },
{ name: 'cookie2', value: 'your-cookie' }
]Parameters
cookies: Cookie[]
url: string
Returns void
setCookiesFromResponse
Saves cookies from an HTTP response to be used with the session. It expects an object with a
headersproperty that's either anObject(typical Node.js responses) or aFunction(Puppeteer Response).It then parses and saves the cookies from the
set-cookieheader, if available.Parameters
response: IncomingMessage | BrowserLikeResponse | { headers: Dictionary<string | string[]>; url: string }
headers: Dictionary<string | string[]>
url: string
Returns void
Sessions are used to store information such as cookies and can be used for generating fingerprints and proxy sessions. You can imagine each session as a specific user, with its own cookies, IP (via proxy) and potentially a unique browser fingerprint. Session internal state can be enriched with custom user data for example some authorization tokens and specific headers in general.