Tolstoy AI Widgets can send engagement events to Google Analytics 4 (GA4), helping you measure widget visibility, interaction, video engagement, quiz behavior, product clicks, and other template-specific actions alongside the rest of your storefront analytics.
How to Set Up
Before you begin
A GA4 property and ID, such as G-XXXXXXXXXX.
A storefront that already exposes gtag or dataLayer. AI Widgets do not load the Google Analytics script.
Analytics consent must allow tracking. If a visitor has not granted the required consent, GA4 events may not be processed.
Access to the AI Widget’s Analytics plugin settings, or an inherited account-level GA4 ID.
Connect GA4
Step 1: Open the AI Widget you want to track in Tolstoy.
Step 2: Open the widget’s Analytics plugin or analytics settings.
Step 3: Enter or confirm the GA4 ID. If your account provides an inherited GA ID, confirm that the correct property is selected.
Step 4: Save your changes.
Step 5: Confirm that Google Analytics is already installed on the storefront and that either gtag or dataLayer is available.
GA4 Event Reference
The events available depend on the widget template and the actions a shopper performs. Custom widget code may also add events.
Core events
GA4 event | What it tracks | Key properties |
embedView | The widget became visible or entered the viewport. | parentUrl, asset count, product context, variant or test group when available |
sessionStart | The shopper’s first interaction with the widget. Ad-page templates may start immediately. | parentUrl, product or variant IDs, page or test group, and Tapcart identifiers when available |
videoLoaded | A native video started or loaded in a supported template. | Asset, video, and product context |
videoWatched | A native video watch session ended after at least one second watched. | videoDuration, videoWatchedTime, videoLoopCount, isVideoSeeked, and asset/video/product context |
Ad pages, feeds, carousels, and video
GA4 event | What it tracks | Key properties |
ad_landing_page_cta_click | Ad landing page CTA clicked. | text, parentUrl, testGroup |
shopify_ad_page_cta_click | Shopify ad page CTA clicked. | ctaId, text, parentUrl, pageId, pagePath, testGroup |
bubble_feed_bubble_click | Bubble Feed opened. | parentUrl; optional assetId |
bubble_feed_bubble_dismiss | Bubble Feed dismissed. | parentUrl |
carousel_card_click | Carousel card clicked or opened. | text containing the asset ID |
embed_video_play | Embedded video started playing. | parentUrl |
hero_video_play | Hero video started playing. | parentUrl |
for_you_feed_feed_close | For You Feed closed. | parentUrl |
tapcart_for_you_feed_feed_close | Tapcart For You Feed closed. | appKey, widgetId |
Collection Tile
GA4 event | What it tracks | Key properties |
collection_tile_tile_view | Collection tile became visible. | parentUrl, assetId, productId |
collection_tile_video_play | Collection tile video played. | parentUrl, assetId, productId |
collection_tile_product_click | Collection tile product clicked. | Asset/video/product IDs, product title, and current-page product ID |
Interactive Quiz
GA4 event | What it tracks | Key properties |
interactive_quiz_answer_click | Quiz answer selected. | questionId, answerId, label |
interactive_quiz_answer_url_click | Quiz answer with an outbound URL clicked. | questionId, answerId, url |
interactive_quiz_back_click | Quiz back navigation clicked. | fromQuestionId, toQuestionId |
interactive_quiz_email_submit | Quiz email submitted. | Common GA4 properties only |
interactive_quiz_result_view | Quiz result screen viewed. | resultId, productCount |
interactive_quiz_product_click | Recommended quiz product clicked. | externalProductId, resultId |
interactive_quiz_cta_click | Quiz result CTA clicked. | url |
interactive_quiz_marketing_event_sent | Quiz completion marketing event attempted or sent. | eventType, outcome |
PDP Stories, reviews, and Spotlight
GA4 event | What it tracks | Key properties |
pdp_stories_video_circle_click | PDP story circle clicked. | assetId |
review_videos_video_circle_click | Review video circle clicked. | assetId |
spotlight_product_click | Spotlight product card clicked. | Asset, video, and product context |
tapcart_pdp_stories_product_click | Tapcart PDP story product clicked. | Asset, video, and product context |
tapcart_pdp_stories_spotlight_click | Tapcart PDP story tile or subtitle clicked. | source, assetId, productId |
Product Gallery
GA4 event | What it tracks | Key properties |
product_gallery_experiment_view | Product Gallery experiment variant rendered. | productMedia, currentPageProductId, testGroup, experiment data in customParams |
product_gallery_thumbnail_click | Product Gallery thumbnail clicked. | mediaIndex and product/test context |
product_gallery_arrow_click | Previous or next gallery arrow clicked. | direction and product/test context |
product_gallery_gallery_swipe | Product Gallery swiped. | direction and product/test context |
product_gallery_variant_switch | Shopify product variant changed in the gallery. | variantId and product/test context |
Tapcart Product Gallery
GA4 event | What it tracks | Key properties |
tapcart_product_gallery_image_change | Product Gallery image changed in Tapcart. | direction, index, and experiment/test context |
tapcart_product_gallery_variant_select | Variant option selected in Tapcart Product Gallery. | optionName, value, variantId, and experiment/test context |
tapcart_product_gallery_cart_add | Add to cart clicked in Tapcart Product Gallery. | variantId and experiment/test context |
Custom events
Custom widget code can send additional events. Their GA4 names use this format:
Naming format: <analyticsSource>_<event_name>. Punctuation is replaced with underscores. |
Best Practices
· Use sessionStart as the primary AI Widget interaction event.
· Use embedView without sessionStart to identify shoppers who saw the widget but did not interact.
· Include widget_id in reports so you can compare individual widgets.
· Validate tracking in GA4 DebugView after initial setup and after changing the widget template or analytics configuration.
· Keep legacy and AI Widget event names together in historical reports during migration.
· Document any custom events added through widget code so dashboard owners understand their source and properties.
Troubleshooting and FAQs
What replaces tolstoyStarted for AI Widgets?
Use sessionStart. It records the shopper’s first interaction with an AI Widget.
Recommended historical segment: event_name = tolstoyStarted OR event_name = sessionStart |
How can I segment shoppers who saw the widget but did not interact?
Create a segment for users who triggered embedView but did not trigger sessionStart.
Why do I not see pageView in GA4?
This is expected. AI Widgets send pageView to Tolstoy analytics, but the analytics plugin does not forward pageView to GA4. Use embedView for widget visibility in GA4.
Why are no Tolstoy events appearing in GA4?
· Confirm the correct GA4 ID is saved in the Analytics plugin or inherited account settings.
· Confirm the storefront already exposes gtag or dataLayer.
· Confirm analytics consent has been granted during the test.
· Test on the published storefront, then use GA4 DebugView or Realtime.
· Perform an action supported by the widget template. Not every template sends every event.
Why does an expected template event not appear?
Template-specific events only fire when the corresponding template and shopper action are used. Confirm the live widget template, publish the latest version, and repeat the exact action while monitoring DebugView.
Do AI Widgets use the same events as legacy Tolstoy widgets?
No. GA4 support remains available, but AI Widgets use the updated event names listed in this article. Update dashboards, audiences, explorations, and reports that rely only on legacy event names.
What should I include when contacting Support?
· The widget ID and live page URL.
· The GA4 ID, with any sensitive account details removed.
· The event name you expected and the action used to trigger it.
· A screenshot from GA4 DebugView or Realtime.
· Whether gtag or dataLayer is available and whether analytics consent was granted.