TypeScript icon, indicating that this package has built-in type declarations

    0.2.2 • Public • Published


    NPM version build status Maintainability Test Coverage

    How many sessions does it take for a user to create an account or purchase something?
    Now you can track these metrics!

    What is a session anyway?
    This is how a web session is defined by Google Analytics:

    a period of time (30 minutes by default) that is extended automatically upon user interaction.

    How does it end?

    • after 30 minutes of inactivity.
    • at midnight (based on your GA settings, not client timezone).
    • campaign query change (utm or gclid)

    A simple demo for the react implementation of this library that you can use to inspect the session data:

    Edit react-web-session demo


    npm install --save web-session

    And create a new session:

    import WebSession from 'web-session';
    const webSession = new WebSession();
    // Initialize your session
    // After a location change or analytics event dispatched, call this function to update the session.


    Type Definition
    type AnyObject<T = any> = Record<string, T>;
    type NarrowPlainObject<T> = Exclude<T, any[] | ((...items: any[]) => any)>;
    interface Options {
       * A function called on every update that receive the session data.
       * @default noop
      callback: (session: Session) => void;
       * The session duration in minutes
       * @default 30
      duration: number;
       * The max history size
       * @default 50
      historySize: number;
       * The session name
       * @default 'WebSessionData'
      name: string;
       * The session timezone used in GA
       * @default 'UTC'
      timezone: string;
    interface Origin {
      createdAt: string;
      href: string;
      referrer: string;
    interface Session {
      current: CurrentSession;
      data?: AnyObject;
      history: Origin[];
      origin: Origin;
      visits: number;

    constructor(options?: Partial<Options>)
    Create a new instance.

    init(options?: Partial<Options>)
    Initialize the session. You can change the session options here.

    update<T = AnyObject>(data?: T & NarrowPlainObject, replaceData = false)
    Update/Replace the session data.

    Get the current session.

    Session data

      origin: {
        createdAt: '2000-01-01T00:15:00.000Z',
        href: '/',
        referrer: ''
      current: {
        campaign: {},
        expiresAt: '2000-01-01T00:15:00.000Z',
        href: '/',
        referrer: ''
      data: { // if using the optional data parameter with update
        something: true
      history: [ // the different campaigns the user has entered in your site
          createdAt: '2000-01-01T00:15:00.000Z',
          href: '/cpc?utm_source=cpc',
          referrer: ''
      visits: 1


    Counting web sessions with JavaScript by @Swizec
    How a web session is defined in Analytics


    npm i web-session

    DownloadsWeekly Downloads






    Unpacked Size

    50 kB

    Total Files


    Last publish


    • gilbarbara