Time to build: approx. 1 hour
To get the most out of this tutorial, you will need:
Product recommendation quizzes are a powerful tool to build engaging sales experiences for shoppers on online stores by allowing them to map their problems or concerns to a product that best meets their needs. For Shopify merchants, this can be an appealing proposition – with an app that lets them build dynamic quizzes, they can present their shoppers with a tailored experience that can result in more conversions and higher satisfaction by matching the right shopper with the right products.
In under an hour, we can create a lightweight, customizable product recommendation quiz app using Gadget, connect the results to products in a Shopify merchant’s store, and build both an embedded in-theme quizlet and a stand-alone quiz web application hosted on Vercel. This app will allow a merchant to create quizzes quickly and then serve a quiz or quizzes to their shoppers wherever they may be.
In our example, we will build a product recommendation quiz that recommends the appropriate skincare bundle from four options based on the shopper's answers. We can also configure the app to track the conversion state of each response to any quiz, giving the merchant rich information about the effectiveness of their quiz or quizzes.
We need a way to create, serve, and record quiz responses in our app. The recording of responses enables us to track the conversion state we discussed above, effectively making a response to a quiz a snapshot of a session that a shopper has with our quiz. Going forward, to distinguish between the models and the concepts they represent, we’ll refer to the models in the title case (e.g. a Result model vs result in reference to an outcome).
In terms of object relationships, a Quiz itself has one-to-many Questions, and each Question can have one-to-many Answers. As an instance of taking the Quiz, a Response belongs to a Quiz, has one-to-many Answers, and has one Result based on the selected Answers.
But how do the Answers lead to a Result? We can build a mapping interface to allow us to select which Answers link to which Result as a part of our app’s admin UI.
Here’s a diagram to demonstrate what relationships our models will have with each other:
Head over to “app.gadget.dev” and authenticate with Google, Github, or create/log in to your account. Next, Gadget will prompt you to create a new application. Click “Create App,” and Gadget will bring you into your new application.
To recommend products to shoppers, we’ll need product data in our app that we can map to the results of a product recommendation quiz. Using Gadget's Connections feature, we can connect our app to a Shopify store and pull product data right from the shop.
The Shopify connection provides us with access to any of the models surfaced in Shopify’s Admin API, as well as an authenticated client and webhook consumption. This connection also allows us to sync data between Shopify and Gadget, both scheduled and on-demand.
To use the Shopify connection, navigate to the Connections view in Gadget via the left-hand navigation. Then, at the top right of the Connections view, select “Add Connection.”
Gadget allows you to select only the models you need from Shopify for your application. Each of the scopes listed can grant you access to read or write to many related resources or models. When Gadget receives webhooks relating to your selected resources, it converts the incoming payload into records and maps them to the corresponding model in Gadget. For our app, we’re going to choose the Products scope with write permissions, and within the scope, we need the Product, Product Image, and Product Variant models. You’ll note that selecting the write permissions will give us read as well, automatically.
Now that we have our scope and models selected, we can scroll to the bottom of the Shopify Resources modal to get the connection set up between Gadget and Shopify.
Now, we can go over to the Shopify Partner Dashboard and create a new custom app. Shopify prompts us for our app’s name, URL, and redirection URL. Gadget provides URLs for you, as seen at the bottom of the Shopify Resources modal. Copy those values from Gadget to Shopify, and select “Create app” to save your changes and generate your API keys.
Once your app is created, Shopify generates the API key and API secret key that Gadget needs to complete the connection. Copy these values back over to Gadget, and then you can select “Add app” to complete the connection.
The last step to connecting Gadget and Shopify for our app is to install our app on the shop we wish to sync product data from. In the Shopify Partner Dashboard, click “Select store” under “Test your app” and choose the applicable Shopify store. Follow the prompts, and you should arrive at this screen; you’re now connected.
Now, we can trigger a manual sync between our connected Shopify store and Gadget by selecting “Sync” on the listed connected store.
You’ll notice now on the left-hand side, under Models, Gadget lists all of the Shopify models you’ve selected. These models are perfect copies of the corresponding types and associations in Shopify. Each model comes with a CRUD API (create, read, update, delete/destroy) automatically triggered by incoming Shopify webhooks or by running syncs. These CRUD actions can also be triggered by interacting with the API, giving you control over these records right in Gadget. Additionally, if you’ve selected any Shopify resources, you will also have a Shopify Sync model and a Shopify Shop model in your list of models. Gadget automatically creates these last two models when you configure the Shopify connection, representing the data syncs between Shopify and Gadget and the shop the app is installed on. You can check out the Shopify connection documentation for more information on these models.
Now that we’ve established our connection between Shopify and Gadget and we’ve synced our data, we can build our models for our app.
We need to create models for our app to represent the components of our Quiz; Questions, Answers, Results, Responses, and the Quiz itself. We need to connect these components by their relationships; Gadget’s built-in relationship fields make this connection effortless. Let’s start with the Quiz model.
The Quiz model is the backbone of our application. In our concept, our app can have many instances of Quiz, each representing a unique product recommendation quiz created through the app’s interface. Our Quiz model needs a couple of properties or fields to get started: a title, maybe a description or body content, and some identifying information like an ID.
Creating a new model in Gadget will take care of some of these fields for us automatically. Each model in Gadget comes with four fields: ID, State, Created At, and Updated At.
If we click the + in the Models section of the side nav, we can start our Quiz model:
Up at the top of this schema view, we’ve named the model Quiz, and Gadget has created the API Identifier corresponding to the model’s name. From here, we can add our first field, Title. Title is a string, and we cannot create an instance of Quiz without it. So, let’s select “Add Field” and create our Title field:
Again, naming the field will automatically generate the API Identifier. We can then select the type of data we’re storing in this field, whether or not it has a default value, and any validations we may want to run against this field on object creation. In the case of Title, we want to select the required validation. We can also add a string length range validation to give Title a minimum and maximum length and a uniqueness validation if we want to ensure no two Quizzes have the same title. Let’s add a uniqueness validation.
You may have noticed that adding a uniqueness validation triggered an action by Gadget to scan through any existing Quiz records for Title field data to ensure the constraints are met. This is because you can add new fields to models at any point, not just during creation; this allows you to grow and extend your models with your business needs as your app evolves. Gadget will then take care of any migrations or underlying schema changes for you behind the scenes.
Let’s now add another field to represent the optional body/description text for the Quiz model:
For simplicity’s sake, we’ll set the type to String with no validations.
With that, our Quiz model is done for now, and we can move on to Question.
Let’s create another new model, and call it Question. This model will represent a single Question in a given Quiz. We need just a few fields to get this model going for now: a title and a body, just like Quiz; we also will add three new fields: a sequence, an image URL, and a required field.
To start, let’s add Title and Body to Question. Like Quiz, Title is a required string field, though the uniqueness constraint is unnecessary. Likewise, Body is a string field with no validations. Once added, let’s move to Sequence.
The Sequence field allows us to declare where this Question will appear in the series of Questions. The Sequence field is technically optional; you could simply sort Questions based on the order they are created, alphabetically, or on another field. However, we’ve chosen to add a Sequence field to give you more control.
The Sequence field is going to be a Number field. When you set a field to the Number type, you can declare the number of decimals you anticipate the values stored in this field to contain. As we’re just working with integers, we’ll leave this field as-is. We’re going to declare the default value of this field as 1 to guard against null values in the unlikely case that Sequence may not get set. Finally, we’re going to add the Required validation to prevent us from creating instances of Question without a Sequence value.
The next field we’ll add is Required?, which is a Boolean field that lets us indicate if responding to the given Question is required or not.
Finally, we’ll add the Image URL field. This field uses the URL type, which comes with a special URL validation that parses the input and ensures it is in a valid URL format.
As this field will be optional, that’s the only validation we’ll need.
Now that Question is set, we’re going to need some Answers. On to the next model!
By now, you should be getting a feel for how the Gadget schema editor works and how quickly you can build expressive models with exactly the fields and logic you need. Next on our list, our Answer model needs just two type-based fields: a Text field and a Sequence field. Our Text field will be a String type field with the Required validation, as our Answer needs to have a text body for users to identify which Answer to choose. Our Sequence field is identical to how we configured it for the Question model; a Number field with no decimals, a default value of 1, and the Required validation. Take a moment to add those two fields to our Answer model, and we can move right along to the Result model.
Our Quiz now has a Question model and an Answer model, which means we can now create the Result model to represent the outcome of a given set of Answers for a Quiz. The Result model is also how we’ll connect outcomes to product recommendations once we make our relationship connections. Result has just two type-based fields: a required Body string-type field to represent the outcome, and an optional Image URL URL-type field with the URL validation, if you wish to provide an image as part of the Result.
Our final model for our Quiz app is the Response model. As discussed at the beginning of this tutorial, the Response model represents an instance of taking the Quiz and allows us to track the progress of any given user who has begun taking the Quiz. It will also be a wrapper model that lets us serve a Result to a user by storing the Answers a user has selected and calculating the appropriate Result.
We’re going to add two fields to this model: an Email field to log emails for marketing purposes and a Conversion State field, which will hold what stage of the Quiz the given Response has progressed to.
As in the above screenshot, our Conversion State field is a String-type field, and we’re going to give the field a default value of “New” and make this field required. This way, we have the state for each Response from the start through to the finish.
The Email field type, just like the URL field type, has a built-in validation to ensure the value supplied to this field is in the correct format. Therefore, we’ll leave this field as optional.
In the last few screenshots, you'll have noticed that we have other fields on our models that we haven’t talked about yet that reference other models in our app. Thinking back to our app’s relationship diagram, we know we need to link our models together to represent the conceptual connections they share. This brings us to our next step:
Now that our models are all established, we can connect them using Relationship fields.
First, let’s navigate back to the Quiz model in the schema editor. Then, let’s add a Questions field to represent the connection of instances of the Question model to an instance of Quiz:
Adding a Relationship field is much like adding a Type-based field. Near the bottom of the selection list for the field type, we see Relationships listed. These Relationships and their definitions are similar to the Active Record concept of Associations. If you want to dive deeper into how Relationships work in Gadget, you can read our Relationship and Relationship Fields documentation. For now, we can move forward with the understanding that we can declare a relationship, and Gadget takes care of linking the models together for us without us needing to create and manage foreign keys.
In the case of Questions, we know already that one Quiz has many Questions. So, we can model this relationship using the “Quiz has many Children” Relationship field. Selecting this relationship type allows us to then select what model is the child model:
Once we select Question as the child of Quiz, the schema editor allows us to model what the inverse of the relationship looks like, giving us finer control of the API identifier for this relationship in the generated schema. We’ll just refer to the inverse of the relationship as Quiz, so the relationship is then Quiz has many Questions, and Question belongs to Quiz.
The other two relationships to model on Quiz are Result and Response. Exactly like Question, a Quiz has many Result objects through a Results field, and a Quiz has many Response through a Responses field. You can call the inverse field for both of these relationships Quiz.
If we move over to the Question model now, we’ll see that Gadget has created a Quiz field on Question for us, linking a Question to one Quiz. In addition to being a child of Quiz, Question is a parent model to the Answer model. A Question can have one-to-many Answers, so we can add an Answers field to our Question model that represents this relationship. Go ahead and add this field now:
Answers, as a model, is a child of multiple models. We’ll model these relationships through the parent models, so we can leave Answers as-is and proceed on to Result.
Result is another model that is both a child and a parent in our relationship mapping. We’ll model the parent side of these relationships:
A Result has many Answer objects, as described by an Answers field, and has many Response objects through Responses. This second relationship may seem strange; if we know that Response is an object that wraps and returns Result, why is Result the parent? This allows us to model that a given Result can be linked to many Responses, as every completed instance of Response does return a Result. Otherwise, we’d have to generate a unique Result record for every Response record.
The other relationship to highlight here is a field called Product Suggestion. This field represents the link between a Result and the Shopify Product Variant we’re recommending based on the Answers in a given Response. We can declare this relationship from the child side.
First, we select the belongs to Relationship type and find Shopify Product Variant in the Parent selection:
Once selected, Gadget requires us to create the inverse relationship field on the Shopify Product Variant model. For our app, we’re going to pick has many Result via a Results field, and that will complete the connection.
Interestingly, this means we’ve now extended the Shopify Product Variant model beyond what Shopify provides. These additional fields on this connected model are only visible on the Gadget side of the connection and do not sync back to Shopify. Instead, these fields allow us to decorate connection-based models with whatever additional information or logic we may need for our apps, such as relationships. For more on how you can extend Shopify-provided models with Gadget, check out our guide on the Shopify connection.
Finally, let’s look at the Response model’s relationships. We already have two established for us, as Response belongs both to a Quiz and a Result. We can add one more relationship here to complete our relationship mapping: Response has many Answer records via Answers.
With our models all connected, the schema of our app is complete. We have all the fields and relationships needed to build out our app’s UI, which we will do in a minute. First, however, is one last puzzle piece: how does a Response get a Result? To answer this, we’re going to need to look at the behaviour of the Response model and employ the use of a Code Effect.
We discussed earlier that Gadget creates a CRUD API for you as you generate and decorate your models. While this is useful, sometimes you need more than just CRUD to build your app. Gadget allows you to extend the CRUD actions with logic through code effects, enabling these actions to unlock more functionality for your app as needed.
Looking at the sidebar menu, we’ll see that our currently selected model for the schema editor has two icons: a head with gears and a server stack. The head with gears is our Behavior icon, and the server stack is our Data icon, linking to the data viewer. Let’s select the Behavior icon and open the Behavior editor:
The Behavior editor has two panes: the State Machine on the left and the Actions and States menu on the right. Together, these allow us to add extra logic to standard CRUD actions or add new states and API actions to the model’s interface.
For our app, what we’re concerned with behavior-wise is the Update action. In our app, the Response record will update through a few user actions: starting the quiz, submitting a response to a quiz, and receiving a result. We can use the Conversion State field on the Response model to represent these states that the Response has arrived at by listening on the Update action for a specific value in that field and then execute some logic to attach a Result record to the Response record. However, we only want to do this if we successfully commit this Response record to Gadget, which we can do through the Success Effect.
Let’s open up the Update action and add a Run Code Snippet effect on Success, and name it “calculateResult.js”:
A new page icon will appear: click that, and we’ll be redirected to the code editor to build our effect.
Our code snippet will look like the following:
Copy and paste the above code into your calculateResult.js, and let’s walk through this snippet at a high level:
The mode function below our exported module is the math we use to calculate the most common Result in the list of potential Results.
With our snippet in place, our models created and relationships connected, we’re ready to consume our app’s API and build our front end!
You'll want to do the first portion of the Headless build regardless of your desired outcome, as you'll need the UI to build a quiz before you can serve the quiz to shoppers. If you're going to embed your quiz in your Shopify store, you can skip the "Deploying to Vercel" section and move right along to the "Shopify Build" section. If you're planning on keeping it completely headless, you can stop after the "Deploying to Vercel" section and skip the "Shopify Build" section entirely.
We will build our freestanding app using React and Next.js and use the Polaris library for our components. You can copy the following app into an empty Github repo to get you started. This app provides both the admin-facing and customer-facing UIs; you’ll just need to take a few steps to get up and running.
Once you’ve copied the app into your own empty Github repo, you’ll need to update the following:
Once that’s complete, you may want to run a quick `npx next` in your terminal to boot your app locally and ensure you’ve replaced all values as expected. Then, when the app is running locally at http://localhost:3000, we can test our app and make our first quiz!
Now for the fun part, making a quiz! Take a moment and make a quiz with your app; you can use our demo quiz as inspiration or create your own!
Once your quiz is complete with questions, answers, and results, go ahead and take your quiz.
Now, we can look at records in Gadget and see how our front-end app connects with Gadget through the client and makes API calls against it. If we look at the Quiz data by selecting the Data icon on the Quiz model in the left-hand sidebar, we should see at least one instance of Quiz, including its ID, title, and body. We can also inspect our other records to see how our pieces work together to create our quiz experience.
When you've got a quiz that you're happy with, note the ID of the quiz, if you're planning on building the quiz right into your Shopify store. Otherwise, let's deploy our app to Vercel.
If you’ve never worked with it before, Vercel is a front-end deployment and hosting platform and is particularly useful for Next.js projects like ours. To begin, let’s head to https://vercel.com/new and log in with our Github account. Once you’ve authorized Vercel for your account, you should be able to see your app repo as an available option in Vercel.
Select your repo, and you’ll be able to configure your environment for your first deployment:
For your Framework Preset, select Next.js. Next, ensure that the chosen Root Directory is the root of your app’s directory, and then select Environment Variables. Finally, you’ll add your API key (the same one in your .env file), so your app can authenticate your client at runtime.
Once you’ve added your API key, hit Deploy, and in a moment, your app should be deployed on Vercel. For more on Vercel, check out their excellent Get Started guide.
We’re now left with one final task: embedding our quiz in Shopify.
While we used an NPM package to install our client into our freestanding app, we’ll need another method of calling the client in our Shopify shop’s theme. Gadget allows us to call our API client directly with a script tag.
We only need the client to run to serve the desired product recommendation quiz. In this case, we’ll make a new template for the Page resource and then use it on a page we’ll create to hold the quiz.
In your Shopify admin for your shop, head to Online Store > Themes and select Edit Code under the Actions menu for the theme you wish to edit.
Under Templates, select “Add a new template” and add a template called page.quiz.json.
Replace the generated file with the following JSON:
Next, under Sections, create a new section called quiz-page.liquid. This will be the content that the page.quiz.json file returns.
We’re going to replace this page with the following code:
We just need to replace the "YOUR DIRECT SCRIPT TAG URL HERE" with your script tag, and "YOUR API KEY" with your API key, and we’re ready for the last step: using our client to return a selected quiz.
You’ll need to make one adjustment here: in the quiz query, you just need to replace (id: [YOUR QUIZ ID]) with the ID of the quiz you want to return. Save your changes, and we’re ready to go! Head over to the Pages section of the Shopify admin, and create a new page for your quiz. You can add whatever title and body content you may want for the page and then set the template to use your new quiz template.
Once you save this page, you’re all done! View the page to see your quiz right in your Shopify store, ready to recommend products to your shoppers.
Want to know more about building effortless, expressive apps with Gadget? Check out our Guides and get building today!