Skip to main content

Migration guide: from @elbwalker to @walkerOS

This guide helps you migrate from the old elbwalker packages to the new walkerOS packages.

Quick reference​

Core package changes​

  • @elbwalker/walker.js → @walkeros/collector + @walkeros/web-source-browser
  • @elbwalker/types + @elbwalker/utils → @walkeros/core
  • @elbwalker/destination-web-* → @walkeros/web-destination-*
  • @elbwalker/destination-node-* → @walkeros/server-destination-*

Step-by-step migration​

1. Update dependencies​

Before:

Loading...

After:

Loading...

2. Update imports​

Before:

Loading...

After:

Loading...

3. Update function calls​

Before:

Loading...

After:

Loading...

Breaking changes​

1. Unified collector​

  • Single @walkeros/collector package works across all platforms
  • Use startFlow() instead of Walkerjs() or createSourceNode()

2. Modular sources​

  • DOM tracking is now @walkeros/web-source-browser
  • Import and initialize sources separately

3. Core package merger​

  • All types and utilities now come from @walkeros/core
  • Update all import statements accordingly

4. Google destinations unified​

  • GA4, Google Ads, and GTM are now unified in @walkeros/web-destination-gtag
  • Configure all Google services through a single destination

Destination configuration patterns​

Unified configuration approach​

Configure all sources and destinations in a single startFlow call:

Loading...

Benefits:

  • Single configuration describing entire tracking setup
  • Full type safety with proper config linking
  • No manual destination registration needed
  • Clean separation between code and configuration

Migration checklist​

Package dependencies​

  • [ ] Remove old @elbwalker/* packages
  • [ ] Add @walkeros/collector
  • [ ] Add required sources and destinations
  • [ ] Add @walkeros/core for custom implementations

Code updates​

  • [ ] Update all imports to new packages
  • [ ] Replace collector initialization with startFlow()
  • [ ] Update type imports to use @walkeros/core
  • [ ] Test functionality after migration

Common issues​

"Cannot find module @walkeros/web-collector"
Solution: Use @walkeros/collector + @walkeros/web-source-browser

"elb is not defined"
Solution: elb is returned by startFlow() function

TypeScript cannot find types
Solution: Import types from @walkeros/core

data-elbaction vs data-elbactions​

Breaking change in @walkeros packages​

The behavior of data-elbaction has changed to improve performance and provide more precise entity targeting:

  • @elbwalker behavior: data-elbaction applied to all entities in the DOM hierarchy
  • @walkeros behavior: data-elbaction applies to nearest entity only

Migration strategy​

Replace data-elbaction with data-elbactions to maintain the same behavior:

Loading...

Use data-elbaction for more precise, performance-optimized tracking:

Loading...

When to use each​

Use data-elbaction (nearest entity) when:

  • You want precise tracking of only the specific entity
  • Performance is critical (fewer events)
  • Implementing new features

Use data-elbactions (all entities) when:

  • Migrating from @elbwalker and need same behavior
  • You need context from parent entities
  • Analytics requires full DOM hierarchy

Tagger API​

The tagger also provides both methods:

Loading...

visible vs impression triggers​

Breaking change in @walkeros packages​

The visibility trigger names have been updated to better reflect their behavior:

  • visible trigger: Now fires multiple times when element re-enters viewport (was visibles)
  • impression trigger: Fires once only when element first becomes visible (was visible)

Migration strategy​

Update your HTML to use the new trigger names:

Loading...

Option 2: understand the behavior change​

If you keep using the old names, understand the behavior has changed:

  • Old visible behavior (single-fire) → Now use impression
  • Old visibles behavior (multiple-fire) → Now use visible

When to use each​

Use impression trigger when:

  • You want to track when content is first seen
  • Measuring ad impressions or content views
  • One-time engagement metrics

Use visible trigger when:

  • You want to track repeated interactions
  • Measuring scroll behavior or re-engagement
  • Analytics requires multiple visibility events

Tagger API​

The tagger supports both trigger types:

Loading...
💡 Need Professional Support?
Need professional support with your walkerOS implementation? Check out our services.