Shopify Theme Extension

The ShopperQuiz widget embeds on your Shopify storefront using a Theme App Extension — a native Shopify feature that lets apps add blocks to your theme without touching any code. It works with any theme that supports Online Store 2.0, which includes all modern Shopify themes.

Why the quiz needs its own page

The ShopperQuiz widget is a complete standalone experience — it has its own welcome screen, question flow, and results screen with product recommendations and cart buttons. When placed on a page, it takes over the full content area and covers everything on that page.

Placing it on an existing page like your homepage or a product page means the quiz will cover all the content on that page — the quiz takes over the full screen and fills the entire content area. A dedicated page — something like /pages/hair-quiz or /pages/find-your-match — gives the widget the space it's designed for and gives shoppers a clean, focused experience with nothing underneath.

A dedicated page also gives you a shareable link you can promote anywhere: email campaigns, social media, a homepage banner, a pop-up, or a product page button.

Step 1 — Get your Quiz ID

Open your quiz in the Quiz Builder and click Quiz Settings at the top of the left panel. Your Quiz ID is shown at the top — click Copy to copy it to your clipboard. It's also visible in the URL while you're on the Quiz Builder page, for example: if the URL is app.shopper-quiz.com/abc123/builder, then abc123 is your Quiz ID.

Step 2 — Create a page for your quiz

In your Shopify admin, go to Online Store → Pages and click Add page. Give it a title that makes sense for your quiz, like "Hair Discovery Quiz" or "Find Your Products". Save the page — you don't need to add any content to it, the quiz block will fill the content area.

Step 3 — Add the quiz block in the theme editor

1. Go to Online Store → Themes and click Customize (or Edit theme depending on your Shopify version) on your active theme
2. In the top bar of the theme editor, use the page selector to switch to the quiz page you just created
3. In the template sections panel, look for the content area between the header and footer — this is typically labelled "Page" or "Main content"
4. Click Add section in that area
5. Switch to the Apps tab — this is where Shopify lists all installed app blocks
6. Select ShopperQuiz from the list
7. A Quiz ID field will appear in the settings panel — paste your Quiz ID there
8. The quiz will render immediately in the preview
9. Click Save

The quiz is now live on that page.

tip

Adding the quiz page to your store navigation before opening the theme editor makes it easy to find and switch to in the page selector. It's not required — you can always use the URL bar in the page selector to navigate directly to the page — but it saves a few clicks during setup.

Linking to the quiz

Once embedded, the quiz page is just a regular page on your store with its own URL. You can link to it from anywhere — a button on your homepage, a banner, an email campaign, a social media bio link, or a product page. There's no requirement to add it to your navigation menu — it's just another page link you can place wherever makes sense for your store.

What happens when a shopper exits the quiz

When a shopper clicks the close button inside the quiz widget, they are taken back to the previous page they were on before arriving at the quiz. If they came directly from an external link such as an email or social media post, closing the quiz takes them to the page before that in their browser history — typically your homepage or wherever they were before clicking the link.

Keeping the quiz up to date

Once the block is placed in your theme, you don't need to touch Shopify's theme editor again. Any changes you make to the quiz content, questions, styling, or settings in your ShopperQuiz dashboard appear on the storefront automatically. The block in your theme only stores the Quiz ID — everything else is loaded live from ShopperQuiz.