Where-was-i NPM

A plugin for your page to display an interactive history of your users session

Demo

🏠 Homepage

Install

Where Was I? is available as a module through npm or as a CDN.

Npm install:

npm install -S where-was-i

And then in the root of your project:

import whereWasI from 'where-was-i'

whereWasI()

Or via CDN, add Where Was I? with dependencies manually to the <head> element of your site:

<script
  src="//cdnjs.cloudflare.com/ajax/libs/html2canvas/1.4.1/html2canvas.min.js"
  defer
></script>
<script
  src="//cdn.jsdelivr.net/npm/where-was-i@0.4.4/lib/index.iife.min.js"
  defer
></script>

Note: Where Was I? depends on html2canvas, which is not included in the CDN.

Then initiate it:

<script>
  if (typeof WhereWasI !== 'undefined' && typeof html2canvas !== 'undefined') {
    WhereWasI()
  }
</script>

Options

Where Was I? offers a lot of customizability to tailor the plugin to fit your needs

Types

ShowButtonPostionType Specifies the position of the show button.

type ShowButtonPostionType =
  | 'bottom-left'
  | 'bottom-right'
  | 'top-left'
  | 'top-right'

ShowButtonOptions Options for customizing the show button.

type ShowButtonOptions = {
  /** The position of the show button */
  position?: ShowButtonPostionType
  /** Custom HTML for the show button */
  html?: string
  /** Custom color for the show button */
  color?: string
}

FooterOptions Options for customizing the footer.

type FooterOptions = {
  /** Hide the footer */
  hide?: boolean
  /** Custom HTML for the footer */
  customHtml?: string
}

WhereWasIOptions Options for configuring "Where Was I?".

type WhereWasIOptions = {
  /** The title to display in the control panel. @default "Where was i?" */
  panelTitle?: string
  /** The maximum amount of location objects to display */
  maxAmount?: number
  /** The style for the location objects. @default "panel" */
  style?: 'cards' | 'panel' | 'drawer'
  /** How often the screenshot should refresh in milliseconds. @default 15000 */
  screenRefreshRate?: number
  /** Adds filter to which paths should be added as location objects */
  acceptedPaths?:
    | {
        /** Path should contain the following string */
        type: 'contains'
        path: string
      }
    | {
        /** Path should start with the following string */
        type: 'startsWith'
        path: string
      }
  /** Get the content of meta fields to use as metadata along each screenshot */
  metafields?: Array<string | Array<string>>
  /** html2canvas options, see https://html2canvas.hertzen.com/configuration for all options */
  canvasOptions?: CanvasOptions
  /** Set log level */
  logging?: 'debug' | 'default'
  /** Z-index of the container. @default 1000 */
  zIndex?: string
  /** Storage type. @default "session" */
  storage?: 'session' | 'local'
  /** Auto close the drawer/panel when leaving. @default true */
  autoClosing?: boolean
  /** Styling options for the show button */
  showButtonOptions?: ShowButtonOptions
  /** Styling options for the footer */
  footerOptions?: FooterOptions
  /** Flag that the application is a SPA */
  isSpa?: boolean
  /** Callback function for navigating to previous location. Useful for SPAs with custom routing */
  navigationCallback?: (path: string) => void
  /** SPA basepath */
  basePath?: string
}

Example usage

const whereWasIOptions: WhereWasIOptions = {
  panelTitle: 'Recent Locations',
  maxAmount: 10,
  style: 'cards',
  screenRefreshRate: 20000,
  acceptedPaths: {
    type: 'contains',
    path: '/dashboard',
  },
  metafields: ['author', ['date', 'time']],
  canvasOptions: {
    logging: true,
    useCORS: true,
  },
  logging: 'debug',
  zIndex: '1500',
  storage: 'local',
  autoClosing: false,
  showButtonOptions: {
    position: 'bottom-right',
    html: '<img src="/my-icon.svg">',
    color: '#FF0000',
  },
  footerOptions: {
    hide: false,
    customHtml: '<footer>Custom footer</footer>',
  },
  isSpa: true,
  navigationCallback: (path: string) => {
    navigate(path)
  },
  basePath: '/app',
}

whereWasI(whereWasIOptions)