Popularity
1.6
Stable
Activity
9.1
Declining
175
7
9

Description

Walker.js is an open-source event tracker. Easy, standardized & flexible. With walker.js you can capture user events in the browser and send them to any destination - just by setting HTML attributes. Become independent from locked-in analytics systems and set up reliable tracking the moment you design your front-end.

Request Feature Β· Report Bug Β· Say hello

Programming language: TypeScript
License: MIT License

walker.js alternatives and similar libraries

Based on the "Editors" category.
Alternatively, view walker.js alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of walker.js or a related project?

Add another 'Editors' Library

README

walker.js

Walker.js is an open-source event tracker. Easy, standardized & flexible. With walker.js you can capture user events in the browser and send them to any destination - just by setting HTML attributes. Become independent from locked-in analytics systems and set up reliable tracking the moment you design your front-end.

Request Feature Β· Report Bug Β· Say hello

πŸ€“ Usage

You can implement all sorts of front-end user events easily with walker.js. From product and UX events like "newsletter signup", or filter usage, etc. to e-commerce actions like product add to carts or order complete events.

Just set a few HTML attributes

<!-- Generic usage -->
<div
  data-elb="ENTITY"
  data-elb-ENTITY="KEY:VALUE"
  data-elbaction="TRIGGER:ACTION"
/>

<!-- Example usage -->
<div
  data-elb="newsletter"
  data-elb-newsletter="list:analytics_hacks;position:overlay"
  data-elbaction="click:signup"
/>

The result is for example something like this:

dataLayer.push({
  event: 'newsletter signup', // combination of entity and action
  data: {
    // arbitrary set properties with the data-elb-newsletter attribute
    list: 'analytics_hacks',
    position: 'overlay',
  },
  globals: {
    // all set properties with the data-elbglobals attribute
    // Not shown in example usage snippet (data-elbglobals="language:en;test:darkmode")
    language: 'en',
    test: 'darkmode',
  },
  user: {
    // stored user ids (manually added once)
    id: 'userid',
    device: 'cookieid',
  },
  nested: [], // all nested entities within the newsletter
  id: '1647968113641-01b5e2-5', // timestamp, group & count of the event
  trigger: 'click', // name of the trigger that fired
  entity: 'newsletter', // entity name
  action: 'signup', // entity action
  timestamp: 1647968113641, // time when the event fired
  timing: 13.37, // how long it took from the page load to trigger the event
  group: '01b5e2', // random group id for all events on a page
  count: 2, // incremental counter of the events on a page
  version: {
    // Helpful when working with raw data
    walker: 1.4, // used walker.js version
    config: 42, // a custom configuration version number
  },
  walker: true, // flag to filter events
});

You are completely free to define naming conventions. All you need to get started are the entity, action & trigger attributes. Learn more about the elbwalker event model and background in our blog.

  1. You define the entity scope by setting the data-elb attribute with the name of an entity to an element, e.g. data-elb="newsletter".
  2. An action can be added by setting the data-elbaction attribute on the same level or all child elements in combination with a matching trigger, e.g. data-elbaction="click:signup" to fire a newsletter signup event when a user clicks on the tagged element.
  3. (Optional) To define the entities' properties, set the composited attribute data-elb-ENTITY with the name and value, e.g. data-elb-newsletter="list:analytics_hacks;position:overlay".
<body data-elbglobals="language:en;test:darkmode">
  <div data-elb="newsletter" data-elb-newsletter="position:overlay">
    <h1 data-elb-newsletter="list:analytics_hacks">
      Awesome Analytics Hacks Newsletter
    </h1>
    <button data-elbaction="click:signup">Signup</button>
  </div>
</body>

data-elb, data-elbaction and data-elbglobals are reserved attributes whereas data-elb- attributes may be arbitrary combinations based on the related entity name. Actions and properties can be set anywhere inside an elb attribute.

See more πŸ§‘β€πŸŽ“ [tagging examples](./examples) and learn how to tag your website.

πŸš€ Getting Started

Add the walker.js to your website and start tagging. Optionally you can specify destinations.

Installation

Either use the walker.js via npm as a project dependency

npm i @elbwalker/walker.js --save

Or as a script

<script
  class="elbwalker"
  src="https://cdn.jsdelivr.net/npm/@elbwalker/[email protected]/dist/walker.js"
></script>

🎬 Triggers

By using the walker.js you don't have to deal with event listener or mutation observer initialization anymore. The walker comes with a bunch of integrated triggers that will fire your event at the right moment.

<!-- The trigger will fire the "app login" event -->
<b data-elb="app" data-elbaction="TRIGGER:login">...</b>

Trigger Definition load after loading a page when DOM is ready click when the element or a child is clicked visible after the element has been in viewport for at least 50% for one second submit on a valid form submission custom calling elbLayer.push()

For further inspiration, please refer to the industry examples in our docs.

🎯 Destinations

By default all events get pushed into the dataLayer, but you can customize the destinations. Walker.js comes with optional build-in destinations.

Example of adding a GA4 destination:

import GA4 from './destinations/google-ga4'; // Load the destination
GA4.config.measurementId = 'G-XXXXXXX'; // Set all required properties
elbwalker.push('walker destination', GA4); // Add the destination

A destination has a config object and an optional init as well as the push function. As soon as an event triggers the destinations init function gets called once so that all events will get sent to the additional destination now.

See more examples, learn how to customize, or write your own in the [destinations deep dive](./src/destinations/).

πŸ›  Contributing

Any contributions you make are greatly appreciated.

If you have a suggestion that would make walker.js better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Start developing

We highly recommend to follow the test driven development approach. Write your tests by specifying the expected input and output.

  1. Install NPM packages sh npm install
  2. Start developing sh npm run dev
  3. Start developing sh npm run build
  4. Be happy

πŸ‘©β€βš–οΈ License

Distributed under the MIT License. See LICENSE for more information.

Contact

Send us an email if you have any questions or feedback at [email protected]

Want to send the data directly to your Google BigQuery instance? Check out our hosted version at https://elbwalker.com/

(back to top)


*Note that all licence references and agreements mentioned in the walker.js README section above are relevant to that project's source code only.