Web Core Utilities

Web Source code Package

Web core utilities are browser-specific functions designed for client-side walkerOS implementations. These utilities handle DOM interactions, browser information, storage, sessions, and web-based communication.

Installation

Import web utilities from the @walkeros/web-core package:

import { getAttribute, sendWeb, sessionStart } from '@walkeros/web-core';

DOM utilities

getAttribute

getAttribute(element: Element, name: string): string retrieves attribute values from DOM elements with enhanced handling.

const element = document.querySelector('[data-elb="product"]');
const entityType = getAttribute(element, 'data-elb'); // Returns 'product'

Attribute Parsing

splitAttribute

splitAttribute(str: string, separator?: string): string[] splits attribute strings using specified separators.

splitAttribute('id:123,name:shirt', ','); // Returns ['id:123', 'name:shirt']

splitKeyVal

splitKeyVal(str: string): [string, string] splits key-value pairs from attribute strings.

splitKeyVal('id:123'); // Returns ['id', '123']

parseInlineConfig

parseInlineConfig(str: string): Record<string, unknown> parses inline configuration strings from HTML attributes.

parseInlineConfig('tracking:true;debug:false;port:3000');
// Returns { tracking: true, debug: false, port: 3000 }

Browser information

getLanguage

getLanguage(navigatorRef: Navigator): string | undefined extracts the user's preferred language.

getLanguage(navigator); // Returns 'en-US' or user's language

getTimezone

getTimezone(): string | undefined gets the user's timezone from the Intl API.

getTimezone(); // Returns 'America/New_York' or user's timezone

getScreenSize

getScreenSize(windowRef: Window): string returns the window's screen dimensions.

getScreenSize(window); // Returns '1920x1080' or current screen size

Element visibility

isVisible

isVisible(element: HTMLElement): boolean checks whether an element is rendered and not painted over. It does not measure how much of the element is inside the viewport; that is the job of the visible and impression triggers.

const promoElement = document.getElementById('promotion');
if (isVisible(promoElement)) {
  // Element is rendered and nothing else is painted over it
}

This function considers:

• Computed display, visibility, and opacity, including transparent ancestors
• Clipping against the viewport itself, not against ancestor overflow boxes; a parent with overflow: hidden is instead caught incidentally by the occlusion hit test below
• Occlusion, via a hit test at the centre of the element's visible area, so something else painted on top of it counts as not visible

Storage management

Storage Operations

storageRead

storageRead(key: string, storage?: StorageType, env?: StorageEnv): WalkerOS.PropertyType reads data from browser storage with automatic type conversion.

// Default uses localStorage
const userId = storageRead('walker_user_id');

// Use sessionStorage
const sessionData = storageRead('session_data', 'session');

storageWrite

storageWrite(key: string, value: WalkerOS.PropertyType, maxAgeInMinutes?: number, storage?: StorageType, domain?: string, env?: StorageEnv): WalkerOS.PropertyType writes data to storage with expiration and domain options.

// Store with 30-minute expiration
storageWrite('user_preference', 'dark-mode', 30);

// Store in sessionStorage
storageWrite('temp_data', { id: 123 }, undefined, 'session');

// Store with custom domain for cookies
storageWrite('tracking_id', 'abc123', 1440, 'cookie', '.example.com');

storageDelete

storageDelete(key: string, storage?: StorageType, domain?: string, env?: StorageEnv) removes data from storage.

storageDelete('expired_data');
storageDelete('session_temp', 'session');

// Delete a cookie that was written with a domain attribute
storageDelete('tracking_id', 'cookie', 'example.com');

Session management

sessionStart

sessionStart(config?: SessionConfig): WalkerOS.SessionData | void initializes and manages user sessions with automatic renewal and tracking.

// Start session with default config
const session = sessionStart();

// Custom session configuration
const session = sessionStart({
  storage: true,
  domain: '.example.com',
  maxAge: 1440, // 24 hours
  sampling: 1.0, // 100% sampling
});

Session data includes:

• id - Unique session identifier
• start - Session start timestamp
• isNew - Whether this is a new session
• count - Number of events in session
• device - Device identifier
• storage - Whether storage is available

Advanced Session Functions

• sessionStorage - Session-specific storage operations
• sessionWindow - Window/tab session management

Web communication

sendWeb

sendWeb<T>(url: string, data?: SendDataValue, options?: SendWebOptionsDynamic<T>): SendWebReturn<T> sends data using various web transport methods.

// Default fetch transport
await sendWeb('https://api.example.com/events', eventData);

// Use specific transport
await sendWeb(url, data, { transport: 'beacon' });
await sendWeb(url, data, { transport: 'xhr' });

// With custom headers
await sendWeb(url, data, {
  headers: { Authorization: 'Bearer token' },
  method: 'PUT',
});

Transport-Specific Functions

sendWebAsFetch

sendWebAsFetch(url: string, data?: SendDataValue, options?: SendWebOptionsFetch): Promise<SendResponse> uses the modern Fetch API with advanced options.

await sendWebAsFetch(url, data, {
  credentials: 'include',
  noCors: true,
  headers: { 'Content-Type': 'application/json' },
});

sendWebAsBeacon

sendWebAsBeacon(url: string, data?: SendDataValue): SendResponse uses the Beacon API for reliable data transmission, especially during page unload.

// Reliable sending during page unload
window.addEventListener('beforeunload', () => {
  sendWebAsBeacon('/analytics/pageview', { duration: Date.now() - startTime });
});

sendWebAsXhr

sendWebAsXhr(url: string, data?: SendDataValue, options?: SendWebOptions): SendResponse uses XMLHttpRequest for synchronous communication.

// Synchronous request (blocks execution)
const response = sendWebAsXhr(url, data, { method: 'POST' });

Tag Mode loader

moin

moin() lets the walkerOS app open Tag Mode on your page, in the one browser tab the app opened for it. There is nothing to configure. walker.js and the web bundles the CLI builds call it first in their entry, so call it yourself only when you start a flow from your own browser code:

import { moin } from '@walkeros/web-core';

moin(); // once, early, before startFlow

It does nothing unless the page was opened with elbMoin in its address. On such a page it waits for the walkerOS app tab to answer and only then loads the Tag Mode script from https://cdn.walkeros.io; without that answer nothing loads. Without https://cdn.walkeros.io in your Content Security Policy's script-src, nothing loads either, unless the policy uses 'strict-dynamic', which trusts scripts added by a script that carries your nonce.

moin(target?: MoinTarget) takes no argument in normal use: the default, MOIN_PRODUCTION, trusts the walkerOS app at https://app.walkeros.io. MOIN_PARAM is the address parameter, 'elbMoin'.

Web hashing

getHashWeb

getHashWeb(str: string, length?: number): Promise<string> generates SHA-256 hashes using the Web Crypto API.

// Generate hash for fingerprinting
const userFingerprint = await getHashWeb(
  navigator.userAgent + navigator.language + screen.width,
  16,
);
// Returns shortened hash like '47e0bdd10f04ef13'

Configuration types

SendWebOptions

interface SendWebOptions {
  headers?: Record<string, string>;
  method?: string; // Default: 'POST'
  transport?: 'fetch' | 'beacon' | 'xhr'; // Default: 'fetch'
}

interface SendWebOptionsFetch extends SendWebOptions {
  credentials?: 'omit' | 'same-origin' | 'include';
  noCors?: boolean;
  timeout?: number; // Abort the request after this many ms (default 10000)
}

SessionConfig

interface SessionConfig {
  storage?: boolean; // Enable storage persistence
  domain?: string; // Cookie domain
  maxAge?: number; // Session duration in minutes
  sampling?: number; // Sampling rate (0-1)
}

StorageEnv

interface StorageEnv {
  window?: Window & typeof globalThis;
  document?: Document;
}

The optional env parameter on storage functions allows injecting window and document for testing and simulation. When omitted, the global window and document are used.

StorageType

type StorageType = 'localStorage' | 'sessionStorage' | 'cookie';

Usage notes

• Consent Required: Browser information functions may require user consent depending on privacy regulations
• Storage Fallbacks: Storage functions gracefully handle unavailable storage with fallbacks
• Transport Selection: Choose transport based on use case:
  • fetch - Modern, flexible, supports responses
  • beacon - Reliable during page unload, small payloads
  • xhr - Synchronous when needed, broader browser support
• Performance: Session and storage operations are optimized for minimal performance impact

For platform-agnostic utilities, see Core Utilities.