Quiz events for your own tracking

#Four quiz moments

Besides its own analytics, Teacup Quiz announces four moments in each run so your own tools can track them. There’s nothing to turn on in Teacup Quiz: the events are always sent, and your tools listen for the ones they need.

#What each event carries

During an A/B test, shoppers who get the test version send its ID (such as skin-quiz-b) and its name. See A/B tests.

#When each one fires

• Started fires once per run. A shopper who reloads and carries on doesn’t fire it again; Retake the quiz starts a new run, which does.
• Completed fires once per run, when the results show, after the email step if there is one. When results show on a page of your store, it fires on that page. It fires in the browser straight away, so it can include runs that Teacup Quiz’s own analytics don’t count, such as very fast ones.
• Added to cart fires every time a shopper adds from the results: one product, all of them at once, or a close match. Adds elsewhere in your store don’t fire it.
• Lead fires when the shopper submits a valid email address, not when they skip.

None of them fire in the editor’s preview.

#Listening in your theme

Each moment is a browser event on the page’s document, with the parameters in event.detail. Nothing needs to change in your theme for Teacup Quiz to work; this is only for a developer who wants to react to quiz moments in their own code, set up before the quiz loads. To log each finished quiz:

document.addEventListener('teacup:quiz-completed', (event) => { console.log(event.detail.quiz_id, event.detail.quiz_title); });

• Theme events fire for every shopper, whatever they chose in your cookie banner. If your code sends data anywhere, check consent first, for example with Shopify.customerPrivacy.analyticsProcessingAllowed().
• They also fire in test runs (the theme editor, theme previews and visits opened with Open your store), which makes them easy to check in your browser’s console.
• After a successful add to cart, Teacup Quiz also fires teacup:added-to-cart with variantIds, the variant numbers added. Theme code can use it to refresh a cart drawer or cart count.

#The shopper’s answers on your own pages

When a shopper finishes a quiz, Teacup Quiz keeps their answers in their browser’s local storage, under teacup:answers, so a page of your store can use them. A common use: a routine’s landing page that says why it fits, such as “Your skin feels tight or flaky a few hours after washing.”

const answers = JSON.parse(localStorage.getItem('teacup:answers') || 'null');

• It holds the last quiz finished in that browser, and is replaced by the next one. Check t if the answers should only count for a while, such as 30 days.
• It never leaves the browser: Teacup Quiz doesn’t send it anywhere, and neither should your code without the shopper’s consent.
• It isn’t kept when the shopper declines preference cookies in your cookie banner, so your page should still read well without it.
• Your own test runs keep it too, so you can try your page right after taking the quiz.

#Shopify custom pixels

Each moment is also published to Shopify’s customer events, as teacup_quiz_started, teacup_quiz_completed, teacup_add_to_cart and teacup_lead. A custom pixel can subscribe to them and pass them on to any service.

1. In your Shopify admin, go to Settings → Customer events.
2. Click Add custom pixel and give it a name, such as “Teacup Quiz events”.
3. Paste your code. The parameters are in event.customData, for example: analytics.subscribe('teacup_quiz_completed', (event) => { console.log(event.customData.quiz_id); });
4. Set the pixel’s customer privacy settings, then click Save and Connect.

Shopify applies your custom pixel’s privacy settings to these events. They aren’t published during test runs.

#Google Analytics and Google Tag Manager

When Google’s tag (gtag) is on your store’s pages, Teacup Quiz sends each moment to it as an event with the same names (teacup_quiz_started and so on) and the parameters above. Without gtag but with Google Tag Manager’s dataLayer, it pushes them to the data layer instead, with the name as event.

• In Google Tag Manager, use a Custom Event trigger with the event name, and Data Layer Variables for quiz_id, quiz_title and value.
• In Google Analytics 4, the events show under their own names. To report on quiz_id or quiz_title, register them as custom dimensions.

Teacup Quiz sends these only when the shopper allows analytics.

#Meta and TikTok

When the Meta pixel (fbq) is on your store’s pages, each moment goes to it as a custom event: TeacupQuizStarted, TeacupQuizCompleted, TeacupAddToCart and TeacupLead, with the parameters above. The TikTok pixel (ttq) gets the same names. They show under those names in each platform’s events manager.

These are custom events, not Meta’s or TikTok’s standard ones such as Lead. To optimize ads for a quiz moment, create a custom conversion from its event.

Teacup Quiz sends these only when the shopper allows marketing. As with Google, pixels added through a Shopify app usually run in the sandbox and don’t receive them; a custom pixel can pass them on.

#Consent and test runs

Teacup Quiz reads the shopper’s choice from Shopify’s customer privacy settings. When there’s no choice to read, it sends the events.

To check theme events without counting anything, open your store with Open your store from the setup guide and watch your browser’s console. To see events reach Google, Meta or TikTok, take the quiz in a normal visit; that run counts in your analytics like any shopper’s.

These events don’t change Teacup Quiz’s own numbers. For those, see How Teacup counts.