scroll-tracking-walkeros

A lightweight, ready-to-use custom walkerOS source for tracking a users scroll progress through an article or page.
Includes differnt customization possibilities. Supports both CommonJS and ES Modules.

Developed to be used as a source for walkerOS, an open-source event data collection by elbwalker.

📦 Installation

npm install scroll-tracking-walkeros
# or
yarn add scroll-tracking-walkeros

🚀 Usage

You can simply integrate it directly in your usual walkerOS configuration as a source:

// WalkerOS.tsx

import type { Collector, WalkerOS } from '@walkeros/core';
import { startFlow } from '@walkeros/collector';
import { sourceBrowser } from '@walkeros/web-source-browser';
import { sourceScroll } from 'scroll-tracking-walkeros'; // 1. Import it

declare global {
  interface Window {
    elb: WalkerOS.Elb;
    walker: Collector.Instance;
  }
}

export async function initializeWalker(): Promise<void> {
  if (window.walker) return;

  const { collector } = await startFlow({
    run: true,
    consent: { functional: true },
    sources: {
      browser: {
        code: sourceBrowser,
      },
      // 2. Add your scroll tracking source here
      scroll: {
        code: sourceScroll,
      }
    },
    destinations: {
      console: {
        code: {
          type: 'console',
          config: {},
          push(event, data) {
            console.log('Event:', event, data);
          },
        },
      },
    },
  });

  window.walker = collector;
}

There are various customization possibilities to fit your needs perfectly:

scroll: {
  code: sourceScroll,
  config: {
    settings: {
      // 1. Optional: Check scroll position every 10ms (performance optimization -> increase number)
      throttle: 10,
      // 2. Optional: Fire an event every 10% (e.g., 10%, 20%, 30%, 40%)
      threshold: 10,
      // 3. Optional: Only fire a new event if new max has been reached, else: fire every time throttle and threshold are satisfied
      onlyFireOnNewMax: true,
      // 4. Optional: Prefix for name of the event (e.g. "scroll depth")
      prefix: 'scroll',
      // 5. Optional: CSS Selector ID of the content wrapper
      articleSelector: '#main-content' 
    }
  }
}

Settings

| Setting | Scope | Type | Default | Description | | ------------------ | -------- | --------- | ---------------- | ------------------------------------------------------------------------ | | throttle | Optional | number | 250 | How often to check scroll position in ms | | threshold | Optional | number | 10 | At what increments should an event be triggered in % | | onlyFireOnNewMax | Optional | boolean | true | Only fire a new event if new max has been reached, else: fire every time | | prefix | Optional | string | 'scroll' | Prefix for the event name | | articleSelector | Optional | string | '#articlebody' | Selector for the article body |

⚠️ Important

For accurate scroll tracking, wrap your main scrollable content in an element like so and change the id:

<div id="articlebody">
  <!-- Your content -->
</div>

🛠 Development Notes

• Designed for direct WalkerOS integration.
• Dependencies:
  • "@walkeros/core": "^3.2.0"

📜 License

MIT - Developed by sleepycat666 for Public Value Technologies GmbH