Shopify Events (Configure) | Germain Documentation

⚙️ Configure Shopify Events

Configure GermainUX to collect Shopify commerce events and correlate them with customer sessions, Session Replay, conversion funnels, products, errors, and business outcomes.

Examples include product views, cart additions, cart removals, sold-out encounters, checkout activity, purchases, and store-specific customer actions.

ℹ️ How Shopify events are used

Collected events can be used to:

Use
Measure product and collection engagement
Analyze product discovery and search behavior
Understand cart additions and removals
Build conversion funnels
Detect abandonment and friction
Measure checkout completion
Correlate commerce activity with errors and performance
Display meaningful milestones in Session Replay
Trigger alerts, reports, and automation

When displayed on the Session Replay timeline, these events are called Custom Insights. The underlying data remains a Shopify or custom event.

Session Replay reconstructs the customer experience from captured browser events; it is not a video recording.

📌 Prerequisites

Before configuring Shopify events:

Requirement
Deploy GermainUX monitoring for Shopify.
Confirm that customer sessions appear in GermainUX.
Install and configure the GermainUX Shopify App when Shopify Web Pixel and checkout events are required.
Configure the Shopify UX monitoring profile.
Define privacy and consent requirements.
Identify the customer journeys and business outcomes to measure.

📦 Shopify standard events

The GermainUX Shopify integration can collect supported Shopify standard events. Availability depends on the Shopify page, integration method, consent status, and Shopify configuration.

Shopify source event	Recommended GermainUX label	Description
`page_viewed`	Page Viewed	Customer visited a supported page
`collection_viewed`	Collection Viewed	Customer viewed a product collection
`product_viewed`	Product Viewed	Customer viewed a product
`search_submitted`	Search Submitted	Customer performed a storefront search
`cart_viewed`	Cart Viewed	Customer viewed the cart
`product_added_to_cart`	Product Added to Cart	Customer added a product to the cart
`product_removed_from_cart`	Product Removed from Cart	Customer removed a product from the cart
`checkout_started`	Checkout Started	Customer began checkout
`checkout_contact_info_submitted`	Contact Information Submitted	Customer submitted checkout contact information
`checkout_address_info_submitted`	Address Information Submitted	Customer submitted a checkout address
`checkout_shipping_info_submitted`	Shipping Information Submitted	Customer selected or submitted shipping information
`payment_info_submitted`	Payment Information Submitted	Customer submitted payment information
`checkout_completed`	Checkout Completed	Checkout successfully reached the completion event
`alert_displayed`	Checkout Alert Displayed	An inline validation message or warning was displayed during checkout
`ui_extension_errored`	Checkout UI Extension Error	A checkout UI extension failed because of an uncaught exception

Shopify’s standard event names and availability are defined by the Shopify Web Pixels API.

Important checkout-completion behavior

Shopify’s checkout_completed event normally fires once per checkout. For post-purchase offers, it may fire on the first upsell page instead of the Thank You page. If the page responsible for generating the event never loads, the event might not be emitted.

Therefore:

Recommendation
Do not rely only on the Thank You page URL to identify purchases.
Deduplicate purchase events using an approved non-sensitive checkout or order identifier.
Do not assume that a missing `checkout_completed` event always means customer abandonment.
Reconcile conversion reporting with Shopify order data when exact financial reporting is required.

📊 GermainUX Shopify KPIs

Preconfigured Shopify event KPIs include:

KPI
Shopify Product Cart Addition
Shopify Product Cart Removal
Shopify Collection View
Shopify Product Viewing
Shopify Cart View

Additional KPIs may be available depending on the GermainUX version and the events configured for the store.

Custom KPIs can be created for:

Custom KPI
Search Submitted
Search with No Results
Sold Out
Checkout Started
Checkout Step Completed
Checkout Alert
Purchase Completed
Discount Applied
Discount Rejected
Subscription Started
Wishlist Addition
Chat Started
Customer Feedback Submitted
Return Requested

🔧 Configure event collection

Go to:

Germain Workspace > Analytics > UX Monitoring Profiles

Select the profile used by the Shopify store and review the Shopify event or custom event settings.

For each event, configure:

Setting
Source event name
GermainUX display name
Storefront URL or domain
Application
Environment
Event attributes
Success state
Business-process mapping
Privacy exclusions
Session Replay timeline visibility

💡 Basic examples

🛒 Add to cart

Setting	Value
Source event	`product_added_to_cart`
GermainUX event name	`AddToCart`
Recommended KPI	Shopify Product Cart Addition
Success	`true`
Timeline label	Product Added to Cart

❌ Remove from cart

Setting	Value
Source event	`product_removed_from_cart`
GermainUX event name	`RemoveFromCart`
Recommended KPI	Shopify Product Cart Removal
Success	`true`
Timeline label	Product Removed from Cart

🚫 Sold out

SoldOut is normally a custom event or derived insight rather than a Shopify standard Web Pixel event.

Setting	Value
GermainUX event name	`SoldOut`
Source	Theme, product state, inventory response, or custom rule
Success	Usually `false` for the attempted product-selection outcome
Timeline label	Product Sold Out

Define precisely what SoldOut means. For example:

Condition
Product has no available variants
Selected variant is unavailable
Inventory becomes unavailable during cart update
Checkout rejects the item because inventory changed

These conditions should not necessarily share one event if different teams own or resolve them.

📑 Event naming conventions

Use stable and consistent event names.

Recommended format:

Object + Action

Examples:

ProductViewed
AddToCart
RemoveFromCart
CartViewed
CheckoutStarted
CheckoutCompleted
DiscountApplied
SearchSubmitted
SearchNoResults
ProductSoldOut

Avoid:

Avoid
Trailing spaces
Dynamic identifiers in event names
Page-specific variations for the same action
Customer names or email addresses
Long descriptive sentences
Multiple spellings of the same event

Store product, cart, or page details as attributes rather than embedding them in the event name.

🏷️ Recommended event attributes

Capture only the attributes required for analysis.

Attribute	Purpose
`application`	Shopify store or application
`environment`	Production, test, or development
`eventName`	Stable GermainUX event name
`sourceEventName`	Original Shopify event name
`productId`	Product correlation
`productName`	Product-level analysis
`variantId`	Variant-level analysis
`variantName`	Human-readable variant
`collectionId`	Collection correlation
`collectionName`	Collection-level analysis
`quantity`	Item quantity
`price`	Unit or line price
`currency`	Currency of the monetary value
`cartValue`	Cart value at the time of the event
`discountCode`	Sanitized discount identifier when approved
`checkoutStage`	Logical checkout step
`success`	Whether the attempted outcome succeeded
`pageName`	Logical page or route
`source`	Shopify Pixel, RUM JS, custom code, or Engine

Use consistent monetary definitions. Document whether price represents:

Option
List price
Discounted price
Unit price
Line price
Pre-tax value
Post-tax value

Inconsistent price definitions produce inaccurate revenue and conversion analysis.

✨ Create custom Shopify events

Use custom events when Shopify does not provide a standard event for the action or business outcome.

Example:

germainApm.api.createEvent("ProductSoldOut", {
    success: false,
    productId: productId,
    variantId: variantId,
    productName: productName,
    pageName: "Product Detail"
});

Example for a successful discount application:

germainApm.api.createEvent("DiscountApplied", {
    success: true,
    discountCode: sanitizedDiscountCode,
    cartValue: cartValue,
    currency: currency
});

Only reference variables that exist in the store’s implementation. These examples must be adapted to the theme, application, or integration that emits the event.

⛔ Do not duplicate standard events

Before adding custom code, determine whether the GermainUX Shopify App already collects the corresponding Shopify standard event.

For example, do not create a second AddToCart event if product_added_to_cart is already collected and mapped to the Shopify Product Cart Addition KPI.

Duplicate events can inflate:

Impacted metric
Conversion volume
Product engagement
Cart additions
Funnel entry
Purchase totals
Alert counts

🎞️ Configure custom insights for Session Replay

Custom Insights display important Shopify events on the Session Replay timeline, allowing an analyst to move directly to the relevant customer action.

Examples include:

Insight	Insight
Product Viewed	Product Added to Cart
Product Removed from Cart	Sold Out
Search with No Results	Checkout Started
Checkout Alert	Purchase Completed
Customer Feedback Submitted	Chat Started

Add a timeline event

Where available, use the supported Workspace dashboard or Session Replay configuration editor.

For environments that require the Configuration Console:

Open the GermainUX Configuration Console.
Navigate to:

germain.apm > workspace > rcaDashboards
Select the User Session Replay dashboard.
Open the target replay portlet.
Open timelineEvents.
Click Add.
Enter the event-matching and display settings.
Save the configuration.
generate the event in a test session.
Confirm that the insight appears at the correct time in Session Replay.

Custom insights on session replay timeline - GermainUX

The exact path can differ by GermainUX version. Prefer the Workspace configuration editor whenever the setting is exposed there.

⚙️ Timeline-event settings

Configure:

Setting
KPI or event type
Event name
Attribute filters
Display label
Icon or color
Success or failure state
Priority
Tooltip content
Click or drill-through behavior

Use short, customer-journey-oriented labels such as:

Label
Added to Cart
Removed from Cart
Search Returned No Results
Checkout Started
Checkout Alert Displayed
Purchase Completed

🔁 Configure conversion funnels

Map Shopify events to the appropriate business-process steps.

Example purchase funnel:

collection_viewed
product_viewed
product_added_to_cart
cart_viewed
checkout_started
checkout_contact_info_submitted
checkout_address_info_submitted
checkout_shipping_info_submitted
payment_info_submitted
checkout_completed

Not every customer must perform every optional step. Define:

Define
Required steps
Optional steps
Repeated steps
Valid alternative paths
Completion condition
Abandonment timeout
Failure conditions

For example, a returning customer might skip address entry, and a direct product-page visitor might never generate a collection-view event.

Classify alerts and checkout messages

Shopify’s alert_displayed event can represent different types of feedback. Do not classify every alert as an application error.

Classification	Example
User validation	Required address field is empty
User-facing application error	Checkout cannot load shipping rates because the service failed
Payment decline	Issuer rejects the payment
Business rule	Product cannot be delivered to the selected region
Informational warning	Customer is notified of a delivery delay

Use the message, checkout stage, and related network activity to derive the appropriate classification.

Shopify events can contain customer, cart, order, and checkout information.

Do not collect:

Sensitive data
Payment-card numbers
Security codes
Passwords
Authentication tokens
Full billing or shipping addresses
Customer names or email addresses unless explicitly approved
Unfiltered request or response bodies
Sensitive free-text values

Configure:

Control
Consent enforcement
Attribute allowlists
URL sanitization
Input and text masking
Data retention
Role-based access
Store- and region-specific privacy rules

Prefer an allowlist of approved event attributes instead of collecting the complete Shopify event payload.

✅ Validate Shopify events

Use a test store or Shopify test mode whenever possible.

Complete these scenarios:

Scenario
View a collection
Search for a product
Add a product to the cart
Attempt to select a sold-out variant
Start checkout
Trigger safe checkout validation

For every event, verify:

Verify
The event occurs once at the expected time.
Its GermainUX name is correct.
It belongs to the correct application and environment.
Product and variant attributes are accurate.
Quantity, price, and currency are accurate.
The event correlates with the correct session.
It appears at the correct point in Session Replay.
It maps to the correct business-process step.
Sensitive values are absent.
Consent choices are respected.

🔧 Troubleshooting

🔍 An event is missing

Confirm that:

Check
The GermainUX Shopify App or RUM JS is loaded.
The event is available on the current Shopify page.
The event subscription is enabled.
The customer performed the exact action that triggers the event.
Consent permits the event.
The store URL matches the monitoring profile.
The event is not filtered by sampling or privacy rules.
The event is mapped to the expected GermainUX KPI.

🔁 Events are duplicated

Check for multiple collection paths:

Source
GermainUX Shopify App
Shopify Web Pixel
Custom Pixel
Theme JavaScript
Tag manager
Third-party checkout script
Custom GermainUX event

Retain one authoritative source for each business event or configure explicit deduplication.

💳 Checkout events are missing