@walkeros/walker.js 0.0.9 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @walkeros/walker.js
 
+## 0.1.0
+
+### Minor Changes
+
+- fixes
+
+### Patch Changes
+
+- Updated dependencies
+  - @walkeros/web-source-datalayer@0.1.0
+  - @walkeros/web-source-browser@0.1.0
+  - @walkeros/collector@0.1.0
+  - @walkeros/web-core@0.1.0
+  - @walkeros/core@0.1.0
+
+## 0.0.10
+
+### Patch Changes
+
+- Updated dependencies
+  - @walkeros/web-source-browser@0.0.9
+
 ## 0.0.9
 
 ### Patch Changes

package/README.md

@@ -1,8 +1,11 @@
-# Walker.js
+# walker.js
 
-A ready-to-use walkerOS bundle that combines the browser source, collector, and
-dataLayer support into a single JavaScript file. Perfect for quickly adding
-privacy-friendly event tracking to any website.
+Walker.js is a pre-built walkerOS application that combines both the
+[browser](/docs/sources/web/browser/) and
+[dataLayer](/docs/sources/web/dataLayer/) sources with the
+[collector](/docs/collector/) and a default `dataLayer` destination into a
+pre-build package. It's designed for users who want instant web tracking without
+complex setup or configuration.
 
 ## Features
 
@@ -16,27 +19,17 @@ privacy-friendly event tracking to any website.
 - 📦 **Queue support** - Events are queued until walker.js loads (elbLayer)
 - 🧪 **Well tested** - Comprehensive test suite included
 
-## Quick Start
+## Installation
 
-### 1. Add elbLayer Function (Recommended)
+### Option 1: NPM Package
 
-Add this before walker.js loads to queue events:
-
-```html
-<script>
-  function elb() {
-    (window.elbLayer = window.elbLayer || []).push(arguments);
-  }
-</script>
+```bash
+npm install @walkeros/walker.js
 ```
 
-### 2. Include walker.js
+### Option 2: CDN
 
 ```html
-<!-- Recommended: Async loading with configuration -->
-<script async data-elbconfig="elbConfig" src="./walker.js"></script>
-
-<!-- Or from CDN -->
 <script
   async
   data-elbconfig="elbConfig"
@@ -44,98 +37,98 @@ Add this before walker.js loads to queue events:
 ></script>
 ```
 
-### 3. Configure
+## Basic Setup
 
-#### Option A: Default Configuration
+### 1. Add Event Queueing (Recommended)
 
-Just load the `walker.js` script - it will look for `window.elbConfig`:
+Add this script before walker.js loads to queue events during initialization:
 
 ```html
 <script>
-  window.elbConfig = {
-    /* your config */
-  };
+  function elb() {
+    (window.elbLayer = window.elbLayer || []).push(arguments);
+  }
 </script>
-<script async src="./walker.js"></script>
 ```
 
-#### Option B: Named Configuration Object
+### 2. Include Walker.js
+
+```html
+<script async data-elbconfig="elbConfig" src="./walker.js"></script>
+```
 
-Use `data-elbconfig` on the script tag to define the configuration object.
+### 3. Configure Destinations
 
 ```html
 <script>
-  window.trackingConfig = {
-    elb: 'elb', // Global function name
-    name: 'walkerjs', // Global instance name
-    dataLayer: true, // Enable dataLayer integration
+  window.elbConfig = {
     collector: {
       destinations: {
-        // Add your destinations here
+        console: {
+          push: (event) => console.log('Event:', event),
+        },
+        api: {
+          push: async (event) => {
+            await fetch('/api/events', {
+              method: 'POST',
+              body: JSON.stringify(event),
+            });
+          },
+        },
       },
     },
   };
 </script>
-<script async data-elbconfig="trackingConfig" src="./walker.js"></script>
-```
-
-#### Option C: Inline Configuration
-
-Configure directly in the script tag. Use simple key:value pairs separated by
-semicolon.
-
-```html
-<script
-  async
-  data-elbconfig="elb:track;run:true;instance:myWalker"
-  src="./walker.js"
-></script>
 ```
 
-### 3. Track Events
+## Configuration Options
 
-#### Automatic DOM Tracking
+Walker.js supports multiple configuration approaches with different priorities:
 
-Add data attributes to your HTML:
-
-```html
-<!-- Product tracking -->
-<div data-elb="product" data-elb-product="id:123;name:Blue T-Shirt;price:29.99">
-  <button data-elbaction="click:add">Add to Cart</button>
-</div>
+1.  **Script tag `data-elbconfig`** (highest priority)
+2.  **`window.elbConfig`** (default fallback)
+3.  **Manual initialization** (when `run: false`)
 
-<!-- Global properties -->
-<div data-elbglobals="pagetype:product_detail"></div>
+### Settings
 
-<!-- Context information -->
-<div data-elbcontext="section:recommendations"></div>
-```
+| Name        | Type                | Default                                                              | Description                                                                                                      |
+| :---------- | :------------------ | :------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
+| `elb`       | `string`            | `"elb"`                                                              | Global function name for event tracking                                                                          |
+| `name`      | `string`            | `"walkerjs"`                                                         | Global instance name                                                                                             |
+| `run`       | `boolean`           | `true`                                                               | Auto-initialize walker.js on load                                                                                |
+| `browser`   | `object \| boolean` | `{ run: true, session: true, scope: document.body, pageview: true }` | [Browser source configuration](https://www.elbwalker.com/docs/sources/web/browser/)                              |
+| `dataLayer` | `object \| boolean` | `false`                                                              | [DataLayer source configuration](https://www.elbwalker.com/docs/sources/web/dataLayer)                           |
+| `collector` | `object`            | `{}`                                                                 | [Collector configuration](https://www.elbwalker.com/docs/collector/) including destinations and consent settings |
 
-#### Manual Event Tracking
+#### Browser Source Settings
 
-```javascript
-// Using the global elb function
-elb('product add', {
-  id: '123',
-  price: 29.99,
-});
-```
+| Name               | Type      | Default         | Description                       |
+| :----------------- | :-------- | :-------------- | :-------------------------------- |
+| `browser.run`      | `boolean` | `true`          | Auto-start DOM tracking           |
+| `browser.session`  | `boolean` | `true`          | Enable session tracking           |
+| `browser.scope`    | `Element` | `document.body` | DOM element scope for tracking    |
+| `browser.pageview` | `boolean` | `true`          | Enable automatic page view events |
 
-## Configuration
+#### DataLayer Settings
 
-### Configuration Options
+| Name               | Type      | Default       | Description                                |
+| :----------------- | :-------- | :------------ | :----------------------------------------- |
+| `dataLayer`        | `boolean` | `false`       | Enable dataLayer integration with defaults |
+| `dataLayer.name`   | `string`  | `"dataLayer"` | DataLayer variable name                    |
+| `dataLayer.prefix` | `string`  | `"dataLayer"` | Event prefix for dataLayer events          |
 
-Walker.js can be configured in multiple ways:
+#### Collector Settings
 
-1. **Script tag with `data-elbconfig`** - Highest priority
-2. **`window.elbConfig`** - Default fallback
-3. **Manual initialization** - When `run: false`
+| Name                     | Type     | Default                | Description                                                               |
+| :----------------------- | :------- | :--------------------- | :------------------------------------------------------------------------ |
+| `collector.consent`      | `object` | `{ functional: true }` | Default consent state                                                     |
+| `collector.destinations` | `object` | `{}`                   | [Destination configurations](https://www.elbwalker.com/docs/destinations) |
 
 ### Full Configuration Object
 
 ```javascript
 window.elbConfig = {
-  // Global configuration
+  // Global settings
   elb: 'elb', // Global function name (default: 'elb')
   name: 'walkerjs', // Global instance name
   run: true, // Auto-initialize (default: true)
@@ -145,56 +138,118 @@ window.elbConfig = {
     run: true, // Auto-start DOM tracking
     session: true, // Enable session tracking
     scope: document.body, // Tracking scope
+    pageview: true, // Enable automatic page views
   },
 
   // DataLayer integration
   dataLayer: true, // Enable dataLayer
   // or detailed config:
-  dataLayer: {
-    name: 'dataLayer', // DataLayer variable name
-    prefix: 'dataLayer', // Event prefix
-  },
+  // dataLayer: {
+  //   name: 'dataLayer', // DataLayer variable name
+  //   prefix: 'dataLayer', // Event prefix
+  // },
 
   // Collector configuration
   collector: {
     consent: { functional: true }, // Default consent state
     destinations: {
-      // Your destinations
+      // Your destinations here
+      console: {
+        push: (event) => console.log('Event:', event),
+      },
     },
   },
 };
 ```
 
-### Destination Configuration
+### Inline Configuration
 
-```javascript
-const walkerjs = Walkerjs({
-  collector: {
-    destinations: {
-      console: {
-        type: 'console',
-        push: (event) => console.log(event),
-      },
+Configure directly in the script tag using simple key:value pairs:
 
-      api: {
-        type: 'custom-api',
-        push: async (event) => {
-          await fetch('/api/events', {
-            method: 'POST',
-            body: JSON.stringify(event),
-          });
-        },
+```html
+<script
+  async
+  data-elbconfig="elb:track;run:true;instance:myWalker"
+  src="./walker.js"
+></script>
+```
+
+### Named Configuration Object
+
+Use a custom configuration object name:
+
+```html
+<script>
+  window.trackingConfig = {
+    elb: 'track',
+    collector: {
+      destinations: {
+        // Your destinations
       },
     },
+  };
+</script>
+<script async data-elbconfig="trackingConfig" src="./walker.js"></script>
+```
+
+## Usage
+
+### Automatic DOM Tracking
+
+Walker.js automatically tracks events based on HTML data attributes:
+
+```html
+<!-- Product tracking -->
+<div data-elb="product" data-elb-product="id:123;name:Blue T-Shirt;price:29.99">
+  <button data-elbaction="click:add">Add to Cart</button>
+</div>
+
+<!-- Global properties -->
+<div data-elbglobals="pagetype:product_detail"></div>
+
+<!-- Context information -->
+<div data-elbcontext="section:recommendations"></div>
+```
+
+For detailed information on data attributes, see the
+[Browser Source documentation](https://www.elbwalker.com/docs/sources/web/browser/tagging).
+
+### Manual Event Tracking
+
+Use the global `elb` function for manual tracking:
+
+```javascript
+// Simple event
+elb('button click', {
+  label: 'interesting',
+});
+```
+
+### DataLayer Integration
+
+Walker.js can integrate with existing dataLayer implementations:
+
+```javascript
+// Enable dataLayer integration
+window.elbConfig = {
+  dataLayer: true, // Uses window.dataLayer by default
+};
+
+// Existing dataLayer events will be processed
+dataLayer.push({
+  event: 'purchase',
+  ecommerce: {
+    transaction_id: '12345',
+    value: 25.42,
   },
 });
 ```
 
-## Advanced Usage
+## Advanced Features
 
 ### Async Loading & Event Queueing
 
-Walker.js supports async loading with automatic event queueing:
+Walker.js handles async loading gracefully with automatic event queueing:
 
 ```html
 <script>
@@ -204,35 +259,91 @@ Walker.js supports async loading with automatic event queueing:
   }
 
   // 2. Track events immediately (even before walker.js loads)
-  elb('page view');
   elb('product view', { id: '123', name: 'Blue T-Shirt' });
 </script>
 
-<!-- 3. Walker.js will process queued events when it loads -->
+<!-- 3. Walker.js processes queued events when it loads -->
 <script async data-elbconfig="elbConfig" src="./walker.js"></script>
 ```
 
-**Benefits:**
-
-- No timing issues with async scripts
-- Events are never lost
-- Works with any loading strategy (async, defer, dynamic)
-- Zero dependencies for the queue function
-
 ### Build Variants
 
-Walker.js provides multiple build formats:
+Walker.js provides multiple build formats for different environments:
 
 - `walker.js` - Standard IIFE bundle for browsers
 - `index.es5.js` - GTM-compatible ES2015 build
 - `index.mjs` - ES modules for modern bundlers
 - `index.js` - CommonJS for Node.js environments
 
+### Programmatic Usage
+
+Use walker.js programmatically in applications:
+
+```javascript
+import { createWalkerjs } from '@walkeros/walker.js';
+
+const { collector, elb } = await createWalkerjs({
+  collector: {
+    destinations: {
+      console: { push: console.log },
+    },
+  },
+  browser: {
+    session: true,
+    pageview: true,
+  },
+});
+```
+
+## Destination Configuration
+
+Configure multiple destinations for your events:
+
+```javascript
+window.elbConfig = {
+  collector: {
+    destinations: {
+      // Console logging for development
+      console: {
+        push: (event) => console.log('Walker.js Event:', event),
+      },
+
+      // Custom API endpoint
+      api: {
+        push: async (event) => {
+          await fetch('/api/events', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(event),
+          });
+        },
+      },
+    },
+  },
+};
+```
+
+For comprehensive destination options, see the
+[Destinations documentation](https://www.elbwalker.com/docs/destinations/).
+
+## Troubleshooting
+
+### Common Issues
+
+**Events not firing:** Check that walker.js loaded and configuration is valid.
+
+**Missing events:** Ensure event queueing function is added before walker.js.
+
+**Configuration not applied:** Verify `data-elbconfig` points to the correct
+object name.
+
 ## API Reference
 
 ### Factory Function
 
-#### `createWalkerjs(config?): Walkerjs.Instance`
+```typescript
+createWalkerjs(config?: Config): Promise<Instance>
+```
 
 Creates a new walker.js instance with the provided configuration.
 
@@ -241,28 +352,19 @@ Creates a new walker.js instance with the provided configuration.
 - `collector` - The walkerOS collector instance
 - `elb` - Browser push function for event tracking
 
-### Additional Methods
-
-- `getAllEvents(scope?, prefix?)` - Get all trackable events on the page
-- `getEvents(target, trigger, prefix?)` - Get events for a specific element and
-  trigger
-- `getGlobals(prefix?, scope?)` - Get global properties from the page
-
 ### Utility Functions
 
-You can also import and use the utility functions directly:
-
 ```javascript
 import { getAllEvents, getEvents, getGlobals } from '@walkeros/walker.js';
 
-// Get all events on the page
+// Get all trackable events on the page
 const events = getAllEvents();
 
-// Get events for a specific button click
+// Get events for a specific element and trigger
 const button = document.querySelector('button');
 const clickEvents = getEvents(button, 'click');
 
-// Get global properties
+// Get global properties from the page
 const globals = getGlobals();
 ```
 
@@ -287,19 +389,25 @@ npm run dev    # Watch mode
 npm run preview       # Serve examples on localhost:3333
 ```
 
-## License
+## Related Documentation
 
-MIT License - see LICENSE file for details.
+- **[Browser Source](https://www.elbwalker.com/docs/sources/web/browser/)** -
+  Detailed DOM tracking capabilities
+- **[Collector](https://www.elbwalker.com/docs/collector/)** - Event processing
+  and routing
+- **[Destinations](https://www.elbwalker.com/docs/destinations/)** - Available
+  destination options
+- **[DataLayer Source](https://www.elbwalker.com/docs/sources/web/dataLayer/)** -
+  DataLayer integration details
+
+Walker.js combines all these components into a single, easy-to-use package
+perfect for getting started with walkerOS quickly.
 
 ## Contributing
 
 This package is part of the walkerOS monorepo. Please see the main repository
 for contribution guidelines.
 
-## Related Packages
+## License
 
-- [@walkeros/collector](../../../packages/collector) - Core collector
-- [@walkeros/web-source-browser](../../../packages/web/sources/browser) -
-  Browser source
-- [@walkeros/web-source-datalayer](../../../packages/web/sources/dataLayer) -
-  DataLayer source
+MIT License - see LICENSE file for details.