Analytics instrumentation

Overview

Instrumentation is the process of adding code to your storefront to collect data about user interactions and behaviors. This data powers critical Adobe Commerce features and provides valuable insights into your customers’ shopping journey.

Why Instrumentation Matters

User interaction events collected through instrumentation enable:

• Adobe Sensei features: Intelligent merchandising and search result optimization in Live Search
• Product recommendations: Personalized product suggestions based on user behavior
• Performance analytics: Detailed dashboards showing search performance, conversion rates, and user engagement
• Business intelligence: Data-driven insights for inventory management and marketing strategies

Required for Core Features

Live Search and Product Recommendations events are not sent to AEP. For these features to function correctly, you must collect and send user interaction events to Adobe Commerce. Without proper instrumentation, these features will not work as expected.

Adobe Client Data Layer (ACDL)

The Adobe Client Data Layer (ACDL) is a standardized JavaScript framework that simplifies data collection on your storefront. It provides a unified approach to capturing, storing, and transmitting user interaction data.

Key Capabilities

The ACDL enables your storefront to:

• Collect interaction data: Track user behaviors like product views, searches, cart actions, and purchases
• Standardize data format: Ensure consistent data structure across all events
• Manage event timing: Control when and how data is sent to analytics services
• Support multiple integrations: Work seamlessly with Adobe Experience Platform, Analytics, and other tools

Core API Functions

Function	Description	Use Case
push()	Add data or trigger events	Send product view, cart addition events
getState()	Retrieve current data layer state	Access user session or cart information
addEventListener()	Register event listeners	React to specific user actions
getHistory()	View event history	Debug or audit data collection

Built-in Support

The Adobe Commerce boilerplate includes ACDL by default, so you don’t need to install it separately. Drop-in components automatically send events to the data layer.

Configuration

Store Configuration

To enable proper event collection, you need to configure your store’s analytics settings. This configuration tells the instrumentation system about your store’s identity and structure. Refer to the Commerce Configuration documentation for more information.

Required Configuration Parameters

"analytics": {
  "base-currency-code": "USD",
  "environment": "Testing",
  "store-id": 1,
  "store-name": "Main Website Store",
  "store-url": "https://adobe-commerce.example.com",
  "store-view-id": 1,
  "store-view-name": "Default Store View",
  "website-id": 1,
  "website-name": "Main Website"
}

Configuration Parameters Explained

Parameter	Description	Example	Required
base-currency-code	Default currency for your store	"USD", "EUR"	Yes
environment	Current environment type	"Testing", "Production"	Yes
store-id	Unique identifier for your store	1, 2	Yes
store-name	Human-readable store name	"Main Website Store"	Yes
store-url	Your store’s primary URL	"https://example.com"	Yes
store-view-id	Unique identifier for store view	1, 2	Yes
store-view-name	Human-readable store view name	"Default Store View"	Yes
website-id	Unique identifier for website	1, 2	Yes
website-name	Human-readable website name	"Main Website"	Yes

environment

The environment parameter is used to determine the type of environment your store is running in. This is important because it affects how data is collected and processed. Be sure to set this to "Testing" when you are developing your storefront, and "Production" when you are ready to deploy your storefront.

Data Services Configuration

For the instrumentation to work with Adobe Commerce’s data services, you’ll need additional configuration parameters. The easiest way to obtain these is through the magento/module-data-services-graphql module, which exposes the necessary GraphQL endpoints.

Required for Data Services

• Catalog Service credentials: For product data synchronization
• SaaS environment ID: Links your storefront to Adobe Commerce SaaS services
• API keys: Authenticate with Adobe Commerce backend services

Event Collection and Validation

Automatic Event Collection

The Commerce boilerplate includes the Storefront Events Collector, which automatically:

1. Listens for ACDL events: Monitors the data layer for new events
2. Validates event structure: Ensures events conform to required schemas
3. Batches and sends data: Efficiently transmits events to Adobe Commerce
4. Handles errors: Manages network issues and retry logic

Event Types Collected

Your instrumentation will automatically track:

• Shopping events: Cart updates and views (addToCart, removeFromCart, shoppingCartView), page views (pageView, productPageView), checkout (startCheckout, completeCheckout) and more.
• Customer profile events: Customer login (signIn), customer logout (signOut), create account (createAccount), edit account (editAccount).
• Search events: Search query (searchRequestSent) and search results (searchResponseReceived).

Search events

If LiveSearch is not installed and configured, these search events are not sent.

Debugging events

To debug events in your storefront, you can use the AEP Debugger Events view. For instructions on how to use the AEP Debugger video tutorial .

Event Schema Compliance

All events must comply with the schema defined by the Storefront Event SDK. This ensures compatibility with Adobe Commerce services and analytics tools.

Validation and Testing

The following sections describe how to validate and test your event implementation.

Automated Validation

You can validate your event implementation using the ACDL Event Validator. This tool checks:

• Event structure: Verifies required fields are present
• Data types: Ensures values match expected formats
• Schema compliance: Confirms events follow Storefront Event SDK specifications

Performance Recommendation

For optimal performance, Adobe recommends writing events directly to ACDL rather than using the Storefront Events SDK wrapper. Drop-in components handle this automatically, but custom implementations should follow this practice.

Manual Testing Steps

1. Open browser developer tools and navigate to the Console tab
2. Check for ACDL: Verify window.adobeDataLayer exists and contains events
3. Monitor network requests: Look for successful data transmission to Adobe services
4. Validate event data: Inspect event payloads for completeness and accuracy
5. Confirm that event data is collected: To confirm that data is being collected from your Commerce store, use the Adobe Experience Platform debugger to examine your Commerce site.

Debugging events

The AEP Debugger provides an Events view that you can use to examine the events being sent from your Commerce site. For instructions on how to use the AEP Debugger video tutorial .

Common Validation Issues

• Missing configuration: Ensure all required analytics parameters are set
• Incorrect store IDs: Verify store and website IDs match your Adobe Commerce setup
• Network connectivity: Check that your storefront can reach Adobe Commerce endpoints
• Event timing: Confirm events fire at the correct moments in the user journey

Troubleshooting Configuration Issues

Problem: Events not being sent
Solution:

1. Verify your config.json contains all required analytics parameters
2. Check that store IDs match your Adobe Commerce backend configuration
3. Ensure the Storefront Events Collector is loading properly

Problem: Invalid event data
Solution:

1. Use the ACDL validator to check event structure
2. Verify custom events follow the Storefront Event SDK schema
3. Check for JavaScript errors that might corrupt event data

Troubleshooting Integration Issues

Problem: Live Search not receiving data
Solution:

1. Confirm your SaaS environment ID is correctly configured
2. Verify API credentials are valid and have necessary permissions
3. Check that product catalog is properly synchronized

For additional troubleshooting, refer to the Live Search Data Collection documentation.

Best Practices

Implementation Guidelines

• Test thoroughly: Validate events in development before deploying to production
• Monitor regularly: Set up alerts for data collection failures
• Follow schemas: Always comply with Storefront Event SDK specifications
• Optimize performance: Batch events when possible to reduce network overhead

Data Quality

• Validate user inputs: Sanitize data before adding to events
• Handle edge cases: Account for scenarios like network failures or missing data
• Maintain consistency: Use standardized naming and formatting across all events
• Respect privacy: Ensure compliance with data protection regulations