Analytics & Tracking

Overview

In today’s fast-paced e-commerce landscape, understanding customer interaction is essential. The SCAYLE Storefront Application offers a robust, out-of-the-box tracking solution for all essential e-commerce events.

Our tracking implementation is designed to be tracking-solution-agnostic. By utilizing the standard Google Tag Manager (GTM) dataLayer pattern, the Storefront Application provides a generic, structured data stream that can be consumed by any analytics platform (e.g., Adobe Analytics, Plausible, Mixpanel, custom endpoints) by simply configuring the relevant tags within GTM.

This standardized approach enables you to seamlessly monitor user behavior, including key actions such as product browsing, cart and wishlist management, customer authentication, and checkout activities.

Events and Data Collection

At the core of tracking is the capture of user interactions as events. Each event represents a specific action taken by a user in the Storefront Application and includes structured data for analysis.

A typical event includes:

• Event Name: A descriptive label for the action (e.g., search, select_item, add_to_cart).
• Timestamp: The exact time the action occurred.
• Unique Identifier: A way to distinguish individual events.

To provide additional context, each event includes parameters that offer more detailed information. For example, a search event might include: search_term, search_action, and search_destination.

Google Tag Manager and Universal Compatibility

The Storefront Application integrates with GTM as the primary data relay mechanism. GTM acts as a powerful bridge, simplifying the configuration and delivery of event data from your storefront to any analytics platform.

GTM follows an Extract, Transform, Load (ETL) approach:

1. Extract: Captures event data from the storefront and pushes it to the dataLayer.
2. Transform: Allows you to modify or map the data within GTM to match specific platform requirements.
3. Load: Sends the transformed data to the chosen analytics or marketing platforms.

To put this universal compatibility into context, we will use Google Analytics 4 (GA4) as our primary example.

Connecting GTM to Google Analytics 4

To route your storefront data through GTM to GA4s, you must establish a connection using the Google Tag.

1. Link GTM to your GA4 Property

1. In Google Analytics: Navigate to Admin > Data Streams. Select your web stream and copy the Measurement ID (format: G-XXXXXXXXXX).
2. In GTM: Go to Tags > New.
3. Tag Configuration: Select Google Tag.
4. Tag ID: Paste your Measurement ID here.
5. Triggering: Select Initialization - All Pages to ensure the connection starts as soon as the storefront loads.
6. Save the tag as "GA4 - Configuration Tag".

2. Forwarding Custom Events

Once the connection is established, you need to create specific tags for the custom events pushed to your dataLayer.

1. Create a Trigger: Go to Triggers > New > Custom Event. Enter the exact event name used by your storefront (e.g., login).
2. Create a Variable for the Event Parameter:
   1. Go to Variables > User-Defined Variables > New.
   2. Choose Data Layer Variable.
   3. Data Layer Variable Name: status
   4. Name it: dlv - login status
3. Create the Event Tag:
   1. Tag Type: Select Google Analytics: GA4 Event.
   2. Measurement ID: Use your GA4 Measurement ID.
   3. Event Name: Use the variable {{Event}} or type the specific event name.
4. Add Event Parameters: Add a row: Property Name: status | Value: {{dlv - login status}}
5. Trigger: Attach the Custom Event trigger you created.

3. Registering in GA4

To actually see these parameters in your GA4 reports, you must register them as Custom Definitions in the GA4 interface.

1. Go to Admin > Data Display > Custom Definitions.
2. Click Create Custom Dimensions.
3. Enter the Dimension name (the name you want to see in reports).
4. Set the Scope to "Event".
5. Enter the Event parameter (this must match the exact key you used in your code or GTM, e.g., status).

Verifying Data Flow in Google Analytics

To ensure your custom events are being displayed correctly, use these verification methods:

I. Real-Time Testing (The DebugView)

The most reliable way to confirm events are hitting GA4 is the DebugView.

1. In GTM, click Preview and enter your storefront URL.
2. In Google Analytics, go to Admin > DebugView.
3. Perform an action on your site (e.g., log in). You should see the event appear on the timeline in GA4 within seconds.

II. Event Reporting

Once the site is live, custom events will appear in the standard reports: Engagement > Events: Lists all events triggered by users.

E-Commerce Tracking Events

The Storefront Application includes automatic tracking for a wide range of standard e-commerce events, grouped by the customer journey:

• Shop Initialization Events – Triggered when the shop is loaded for the first time.
• Product Interaction Events – Track user interactions with products (e.g., view, add to cart, remove).
• Checkout Funnel Events – Monitor activities throughout the checkout process.
• User Authentication Events – Capture login, signup, and logout actions.
• Search and Filter Events – Track user behavior related to searching and filtering.

For a full list of supported events and their parameters, refer to the Tracking Events documentation. Additionally, the Event Triggering by Page table provides a clear overview of which events are triggered on specific pages.

Event Triggering by Page

How It Works

The Storefront Application tracking module automatically captures events as users interact with the storefront. When a user navigates between pages, adds items to their basket, or completes checkout, tracking events are sent to GTM with enriched context data.

User-Facing Behavior

Automatic Tracking:

• Content views are tracked automatically when users navigate between routes.
• Basket changes (add, remove, quantity updates) trigger tracking events.
• Checkout progress (shipping, payment, completion) is tracked automatically.
• Promotions and campaigns are tracked when they become visible in the viewport.

Manual Tracking:

• Developers can trigger custom events using tracking composables.
• Product interactions (view, select, add to wishlist) can be tracked explicitly.
• Search queries and filter applications are tracked for analytics.

Event Flow

Step-by-Step Flow

1. User Action Trigger

A user action initiates the tracking flow. This can be:

• Navigation: Route changes detected by middleware (automatic)
• User Interaction: Clicks, form submissions, or other UI interactions (manual or automatic)
• Element Visibility: Elements entering the viewport via v-element-visibility directive (automatic)
• State Changes: Basket updates, authentication state changes, or other reactive state mutations (automatic via watchers)

2. Event Capture

The appropriate tracking composable captures the event with relevant data:

• Domain-specific composables (e.g., useProductEvents, useBasketEvents) extract relevant information from the action
• Event-specific data is collected (product IDs, basket items, checkout steps, etc.)
• The composable prepares a partial tracking event object with event-specific properties

3. Context Enrichment

• Page Context: Retrieved from useTrackingContext(), includes:
  • Current route path and page type (from route meta)
  • Previous page path and type (from tracking state)
  • Optional interaction source (provided by the calling composable)
• Session Context: Retrieved from useTrackingContext(), includes:
  • Shop information (ID, currency, locale, version)
  • Landing page URL and query parameters (captured on first load)
  • Referrer information (from document.referrer)
  • User information (customer ID, type, groups, authentication status, email hash)
• Ecommerce Data Clearing: If the event includes ecommerce data, the previous ecommerce object in the dataLayer is cleared first to prevent data pollution between events

4. GTM DataLayer Push

The enriched event is pushed to the GTM dataLayer:

• The useTracking composable calls tagManager.proxy.dataLayer.push() with the complete event object
• The GTM instance must be initialized and available (checked before pushing)

5. GTM Processing

• GTM receives the event in the dataLayer
• Triggers configured based on event name and data
• Tags fire according to trigger conditions (analytics platforms, pixels, etc.)
• Events are forwarded to configured analytics platforms (Google Analytics, Facebook Pixel, etc.)

Error Handling

The tracking flow includes several safety checks:

• SSR Guard: Events are only pushed on the client-side to prevent SSR errors
• GTM Availability Check: Verifies GTM is initialized before pushing
• Data Validation: Composables validate required data before tracking
• Graceful Degradation: If tracking fails, the application continues normally without errors

Middleware

The tracking module uses two global middleware functions to manage context and track navigation:

setupTrackingContext Middleware

The setupTrackingContext middleware is a global route middleware that runs on every client-side navigation to maintain accurate page context for tracking. It performs two distinct operations depending on whether it's the initial page load or a subsequent navigation.

On the first client-side load, Nuxt provides a route object where both from.path and to.path are identical (representing the initial route). When this condition is detected, the middleware captures the complete landing page URL using window.location.href, which includes the full path, query parameters (including UTM parameters), and hash fragments. This comprehensive URL is stored in the tracking state and persists throughout the session, enabling accurate attribution analysis.

For all subsequent client-side navigation, the middleware updates the previous page context by storing the from route's path and page type. The page type is extracted from the route's meta property, which must be defined in each page component using definePageMeta. This previous page information is then available in all tracking events, allowing analytics systems to understand user navigation patterns and measure the effectiveness of different entry points.

typescript

Copy

The middleware includes a server-side guard that immediately returns if executed during SSR, ensuring it only runs in the browser where window.location and navigation state are available. This prevents potential errors and ensures the middleware operates only in the appropriate context.

routeTracker Middleware

The routeTracker middleware automatically tracks content view events whenever users navigate between different routes in the application. It operates as a global middleware, ensuring consistent page view tracking across all navigation events.

The middleware first checks if the navigation represents the initial page load by comparing the from and to route paths. When these paths are identical, it indicates the first client-side render, and the middleware exits without tracking. This is intentional because the initial page view is handled separately by the GTM plugin, which tracks it on the page:loading:end Nuxt hook after user data has been loaded. This separation ensures the initial page view includes complete session context.

For all subsequent navigation where the paths differ, the middleware calls trackContentView() from the useGlobalEvents composable. This function automatically enriches the event with current page and session context, including the previous page information that was set by the setupTrackingContext middleware. The event is then pushed to the GTM dataLayer with all relevant context, enabling comprehensive page view analytics without requiring manual tracking calls in each page component.

Checkout Integration

The checkout page integrates the SCAYLE Checkout Web Component through a message event listener. The web component sends tracking events via postMessage to the parent page. The checkout page registers a message event listener using VueUse's useEventListener composable, which automatically handles cleanup when the component unmounts.

The event handler function receives message events from the web component and examines the event type to determine which tracking function to call. It extracts relevant data from the web component event payload and maps it to the appropriate tracking composable function. This integration ensures all checkout interactions within the web component are properly tracked with the correct context and basket information.

typescript

Copy

For further details, see the Checkout Tracking documentation.

Authentication Tracking

Authentication tracking is implemented in authentication composables or components that handle login and registration forms. After attempting to authenticate a user (either through login or sign-up), the code calls the appropriate tracking function with the result of the operation.

For login and registration attempts, the code typically listens to the auth:success and auth:error events from the checkout web component and calls the appropriate tracking function with the result of the operation. If the source of the event is login or register, the code calls the appropriate tracking function with the result of the operation.

Logout tracking is typically called directly when the logout action is triggered, as logout operations are generally synchronous and don't require result checking.

typescript

Copy

For further details, see the Shop-Side Authentication documentation.