Skip to main content

Web Core Utilities

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}');
// Returns { tracking: true, debug: false }

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 if an element is visible to the user.

const promoElement = document.getElementById('promotion');
if (isVisible(promoElement)) {
  // Element is visible on screen
}

This function considers:

  • Element display and visibility styles
  • Element position within viewport
  • Parent element visibility
  • Intersection with the visible area

Storage Management​

Storage Operations​

storageRead​

storageRead(key: string, storage?: StorageType): 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', 'sessionStorage');

storageWrite​

storageWrite(key: string, value: WalkerOS.PropertyType, maxAgeInMinutes?: number, storage?: StorageType, domain?: string): 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, 'sessionStorage');

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

storageDelete​

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

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

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' });

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;
}

SessionConfig​

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

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.

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