{"id":26804388,"url":"https://github.com/jordanrobo/unified-datalayer","last_synced_at":"2026-05-03T01:38:42.410Z","repository":{"id":284056327,"uuid":"952833131","full_name":"JordanRobo/Unified-DataLayer","owner":"JordanRobo","description":"A multi-framework utility package for managing XP Data Layer events across different platforms, with a focus on Adobe Analytics integration.","archived":false,"fork":false,"pushed_at":"2025-06-03T00:27:18.000Z","size":245,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-05T15:46:02.421Z","etag":null,"topics":["adobe","analytics","data-layer"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/unified-datalayer","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JordanRobo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-22T01:06:37.000Z","updated_at":"2025-06-03T00:27:23.000Z","dependencies_parsed_at":"2025-08-05T15:31:57.907Z","dependency_job_id":"baa3fc12-d1e5-4e84-bc02-60ab6f228f8c","html_url":"https://github.com/JordanRobo/Unified-DataLayer","commit_stats":null,"previous_names":["jordanrobo/xp-datalayer-manager","jordanrobo/unified-datalayer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JordanRobo/Unified-DataLayer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanRobo%2FUnified-DataLayer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanRobo%2FUnified-DataLayer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanRobo%2FUnified-DataLayer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanRobo%2FUnified-DataLayer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JordanRobo","download_url":"https://codeload.github.com/JordanRobo/Unified-DataLayer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanRobo%2FUnified-DataLayer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001320,"owners_count":26083040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adobe","analytics","data-layer"],"created_at":"2025-03-29T22:16:31.926Z","updated_at":"2025-10-09T10:07:17.668Z","avatar_url":"https://github.com/JordanRobo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Unified DataLayer\n\nA multi-framework utility package for managing XP Data Layer events across different platforms, with a focus on Adobe Analytics integration.\n\n[![npm version](https://img.shields.io/npm/v/unified-datalayer.svg)](https://www.npmjs.com/package/unified-datalayer)\n[![license](https://img.shields.io/npm/l/unified-datalayer.svg)](https://github.com/JordanRobo/Unified-DataLayer/blob/main/LICENSE)\n\n## Overview\n\nUnified DataLayer provides a standardised way to interact with Adobe's Data Layer across different web frameworks. It offers module-based architecture for various tracking scenarios like page views, product displays, cart interactions, and more.\n\n## Features\n\n- **Framework Agnostic**: Works with any JavaScript framework (React, Vue, Angular, etc.)\n- **Singleton Pattern**: Consistent access to the data layer across your application\n- **Modular Design**: Separate modules for different tracking scenarios\n- **Smart Nullification**: Automatically handles data layer cleanup between events\n- **Standardised Formatting**: Ensures consistent data structure across all events\n- **Built-in Validation**: Comprehensive input validation with detailed error messages\n- **TypeScript Support**: Full TypeScript definitions included\n\n## Installation\n\n```bash\n# Using npm\nnpm install unified-datalayer\n\n# Using yarn\nyarn add unified-datalayer\n\n# Using bun\nbun add unified-datalayer\n```\n\n## Basic Usage\n\n### Initialisation\n\nInitialise the data layer with your site information:\n\n```typescript\nimport { getDataLayer } from 'unified-datalayer';\n\n// Get the singleton instance\nconst dataLayer = getDataLayer();\n\n// Initialise with site info (required)\ndataLayer.init({\n  siteInfo: {\n    name: 'My Store',\n    experience: 'web',\n    currency: 'USD',\n    division: 'retail',\n    domain: 'mystore.com',\n    env: 'production',\n    version: '1.0.0'\n  }\n});\n```\n\n### Tracking Page Views\n\n```typescript\n// Track homepage view\ndataLayer.page.home();\n\n// Track other page types\ndataLayer.page.view('category');\ndataLayer.page.view('search', 'results');\n```\n\n### Tracking Product Display\n\n```typescript\n// Track product view on PDP\nconst product = {\n  brand: 'Brand Name',\n  category: ['Footwear', 'Running'],\n  child_sku: 'SKU12345',\n  color: 'Blue',\n  full_price: 150,\n  gender: 'Men',\n  listed_price: 150,\n  name: 'Speed Runner 2.0',\n  parent_category: 'Footwear',\n  parent_sku: 'PARENT-SKU',\n  sku_available: true\n};\n\ndataLayer.pdp.view(product);\n\n// Track color selection\ndataLayer.pdp.colorSelect('Red');\n\n// Track size selection\ndataLayer.pdp.sizeSelect('10');\n```\n\n### Tracking Cart Interactions\n\n```typescript\n// Track adding a product to cart\nconst cartProduct = {\n  ...product,\n  qty: 1,\n  size: '10',\n  sku_by_size: 'SKU12345-10'\n};\n\ndataLayer.cart.add(cartProduct);\n\n// Track cart view\nconst cartItems = [\n  { ...cartProduct, qty: 1 },\n  { ...anotherCartProduct, qty: 2 }\n];\n\ndataLayer.cart.fullView(cartItems, { cartId: 'cart123' });\n\n// Track cart updates\ndataLayer.cart.update('SKU12345-10', 2);\n\n// Track cart item removal\ndataLayer.cart.remove('SKU12345-10');\n```\n\n## Available Modules\n\n### Page Module\nHandles tracking for general page views and navigation:\n- `home()`: Track home page view\n- `view(pageType, action?)`: Track any page type view\n- `error()`: Track page errors\n\n### Product Display Module (PDP)\nManages tracking for product detail pages:\n- `view(productData)`: Track product detail view\n- `colorSelect(color)`: Track color selection\n- `sizeSelect(size)`: Track size selection\n\n### Product Listing Module (PLP)\nManages tracking for product listing pages:\n- `view(productsArray, listName?)`: Track product listing view\n- `filter(listFilters)`: Track filter usage\n- `sort(option)`: Track sort option selection\n- `click()`: Track product click (placeholder)\n\n### Cart Module\nManages tracking for cart interactions:\n- `add(product)`: Track adding product to cart\n- `remove(childSku)`: Track removing product from cart\n- `update(childSku, quantity)`: Track updating cart item quantity\n- `miniView(items, cartInfo)`: Track mini cart view\n- `fullView(items, cartInfo)`: Track full cart view\n- `getCartItems()`: Get current cart items\n- `getCartInfo()`: Get current cart information\n\n### Checkout Module\nManages tracking for checkout process:\n- `start()`: Track checkout initiation\n- `step2()`: Track checkout second step\n- `step3()`: Track checkout third step\n\n### Account Module\nManages tracking for user account actions:\n- `createStart()`: Track account creation start\n- `createComplete()`: Track account creation completion\n- `loginStart()`: Track login attempt\n- `loginSuccess()`: Track successful login\n\n### Order Module\nManages tracking for order completion:\n- `success()`: Track successful order completion\n\n### Wishlist Module\nManages tracking for wishlist interactions:\n- `view()`: Track wishlist view\n- `add()`: Track adding item to wishlist\n\n## Data Types\n\n### ProductData Interface\n```typescript\ninterface ProductData {\n  brand: string;\n  category: string[];\n  child_sku: string;\n  color: string;\n  full_price: number;\n  gender: string;\n  listed_price: number;\n  name: string;\n  parent_category: string;\n  parent_sku: string;\n  sku_available: boolean;\n  // Optional fields\n  available_size?: string[];\n  barcode?: string;\n  feature?: string[];\n  rating?: number;\n  reward_points?: number;\n  model?: string;\n  speciality?: string;\n  sport?: string;\n  story?: string;\n}\n```\n\n### CartProductData Interface\n```typescript\ninterface CartProductData extends ProductData {\n  qty: number;\n  size: string;\n  sku_by_size: string;\n}\n```\n\n### ListFilters Interface\n```typescript\ninterface ListFilters {\n  filter_type: string;  // Pipe-separated: \"category|price|color\"\n  filter_value: string; // Corresponding values: \"sneakers|50-100|red,blue\"\n}\n```\n\n## Advanced Configuration\n\n### Property Nullification\n\nConfigure which properties should be automatically nullified between events:\n\n```typescript\n// Set properties to nullify\ndataLayer.setPropertiesToNullify({\n  default: ['error', 'user'],\n  cart: ['cart_item_removed']\n});\n\n// Add properties to nullify \ndataLayer.addPropertiesToNullify('default', ['search']);\n```\n\n### Error Handling\n\nThe library includes comprehensive error handling with detailed error messages. \n\nAll errors are logged to the console and requires no implementation, this is all handled internally.\n\n\n### State Management\n\nAccess current cart state:\n\n```typescript\n// Get current cart items\nconst currentItems = dataLayer.cart.getCartItems();\n\n// Get current cart info\nconst cartInfo = dataLayer.cart.getCartInfo();\n```\n\n## Event Examples\n\n### Product Listing with Filters\n```typescript\n// Track product listing view\nconst products = [\n  {\n    brand: 'Nike',\n    category: ['Footwear', 'Running'],\n    child_sku: 'NIKE-RUN-001',\n    color: 'Black',\n    full_price: 120.00,\n    gender: 'Men',\n    listed_price: 99.99,\n    name: 'Air Max Runner',\n    parent_category: 'Footwear',\n    parent_sku: 'NIKE-RUN',\n    sku_available: true\n  }\n];\n\ndataLayer.plp.view(products, 'Running Shoes');\n\n// Track filter application\ndataLayer.plp.filter({\n  filter_type: 'category|price|color',\n  filter_value: 'running|50-150|black,white'\n});\n\n// Track sorting\ndataLayer.plp.sort('price_ascending');\n```\n\n### Account Creation Flow\n```typescript\n// Track account creation start\ndataLayer.account.createStart();\n\n// After successful registration\ndataLayer.account.createComplete();\n\n// Track login attempts\ndataLayer.account.loginStart();\n\n// After successful login\ndataLayer.account.loginSuccess();\n```\n\n## Development\n\n### Prerequisites\n\n- [Bun](https://bun.sh/) (for building and testing)\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/JordanRobo/Unified-DataLayer\ncd unified-datalayer\n\n# Install dependencies\nbun install\n```\n\n### Scripts\n\n```bash\n# Build the package\nbun run build\n\n# Generate TypeScript declarations\nbun run build:types\n\n# Run development mode with watch\nbun run dev\n\n# Run tests\nbun run test\n\n# Build and prepare for publishing\nbun run prepare\n```\n\n### Testing\n\nThe package includes a comprehensive test suite with an interactive HTML test page:\n\n```bash\n# Open test/index.html in a browser to test all functionality\n# The test page includes:\n# - All module testing\n# - Error handling validation\n# - Real-time data layer state inspection\n# - Console output monitoring\n```\n\n## Browser Compatibility\n\n- Modern browsers with ES6+ support\n- Adobe Client Data Layer integration\n\n## License\n\nThis project is licensed under the BSD 3-Clause License - see the LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjordanrobo%2Funified-datalayer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjordanrobo%2Funified-datalayer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjordanrobo%2Funified-datalayer/lists"}