Skip to main content
Version: 3.11

Session

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.

Index

Constructors

Properties

Methods

Constructors

constructor

Properties

readonlyid

id: string

userData

userData: Dictionary

Methods

getCookieString

  • getCookieString(url: string): string

  • 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 Cookie header.

getCookies

  • getCookies(url: string): Cookie[]

  • 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

  • isBlocked(): boolean

  • Indicates whether the session is blocked. Session is blocked once it reaches the maxErrorScore.

    Returns boolean

isExpired

  • isExpired(): boolean

  • Indicates whether the session is expired. Session expiration is determined by the maxAgeSecs. Once the session is older than createdAt + maxAgeSecs the session is considered expired.

    Returns boolean

isMaxUsageCountReached

  • isMaxUsageCountReached(): boolean

  • Indicates whether the session is used maximum number of times. Session maximum usage count can be changed by maxUsageCount parameter.

    Returns boolean

isUsable

  • isUsable(): boolean

  • 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

  • markBad(): void

  • Increases usage and error count. Should be used when the session has been used unsuccessfully. For example because of timeouts.

    Returns void

markGood

  • markGood(): void

  • This method should be called after a successful session usage. It increases usageCount and potentially lowers the errorScore by the errorScoreDecrement.

    Returns void

retire

  • retire(): void

  • Marks session as blocked and emits event on the SessionPool This 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 use markBad method.

    Returns void

retireOnBlockedStatusCodes

  • retireOnBlockedStatusCodes(statusCode: number): boolean
  • retireOnBlockedStatusCodes(statusCode: number, additionalBlockedStatusCodes?: number[]): boolean

  • With certain status codes: 401, 403 or 429 we 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

  • setCookie(rawCookie: string, url: string): void

  • Sets a cookie within this session for the specific URL.

    Parameters

    • rawCookie: string
    • url: string

    Returns void

setCookies

  • setCookies(cookies: Cookie[], url: string): void

  • 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

    Returns void

setCookiesFromResponse

  • setCookiesFromResponse(response: IncomingMessage | BrowserLikeResponse | { headers: Dictionary<string | string[]>; url: string }): void

  • Saves cookies from an HTTP response to be used with the session. It expects an object with a headers property that's either an Object (typical Node.js responses) or a Function (Puppeteer Response).

    It then parses and saves the cookies from the set-cookie header, if available.

    Parameters

    • response: IncomingMessage | BrowserLikeResponse | { headers: Dictionary<string | string[]>; url: string }
      • headers: Dictionary<string | string[]>
      • url: string

    Returns void

Page Options