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

    0.2.2 • Public • Published

    web-session

    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

    Usage

    npm install --save web-session

    And create a new session:

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

    API

    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.

    session
    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
    })

    References

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

    Install

    npm i web-session

    DownloadsWeekly Downloads

    67

    Version

    0.2.2

    License

    MIT

    Unpacked Size

    50 kB

    Total Files

    24

    Last publish

    Collaborators

    • gilbarbara