Trivia Scoring Quiz — Complete User Guide
Version: 1.0
Overview
Trivia Scoring Quiz is a HubSpot module for building interactive knowledge assessments with objective right/wrong scoring, instant answer feedback, score-based result ranges, and seamless CRM integration. Unlike opinion-based quizzes, every question has one correct answer — and the module always reveals it, along with a custom explanation you write.
Use Cases:
- Industry knowledge assessments and certification-style lead magnets.
- Product education quizzes that qualify and inform prospects simultaneously.
- Branded trivia content for blogs and landing pages to increase dwell time.
- Interactive onboarding checks that segment contacts by knowledge level.
How It Works (Technical Concept)
To configure this module correctly, it helps to understand the data flow:
- The Quiz UI: Users interact with a fully custom, multi-step interface — Intro → Questions → Lead Capture Form → Results.
- Scoring Logic: After each answer, the module marks the response as correct or incorrect and reveals the correct choice plus your explanation. The final score equals the total number of correct answers.
- Result Matching: The final score is compared against the score ranges you define. The first range whose
min_score ≤ score ≤ max_score threshold is matched, and its result screen is shown.
- Data Transport: A standard HubSpot Form is used "under the hood" as a data receiver. The native form UI is replaced by the quiz interface, but a valid Form ID is required to save contacts and quiz data to the CRM.
Settings Structure
The documentation follows the exact order of the module configuration groups:
- Intro Step
- Questions
- Results & Ranges
- Lead Capture Form
- UI Settings & Labels
- CRM Data Sync
- Advanced Settings
- Design & Style (Style Tab)
PART 1. CONTENT & LOGIC
1. Intro Step
The first screen users see. Use it to explain what the quiz is about and motivate them to begin.
- Title: Main headline (e.g., "Test Your Knowledge!").
- Description: Richtext introductory text. Explain the topic, number of questions, or what the user will learn.
- Start Button Text: Label for the CTA button (e.g., "Start the quiz").
2. Questions
This section defines the quiz questions and their answer choices.
2.1 Adding Questions
Click Add in the Questions repeater to create each question. For each question, you define:
- Question Prompt: The question text shown to the user.
- Question Helper Text: Optional richtext hint displayed below the question (e.g., a clarifying note or image context). Leave empty if not needed.
2.2 Answers & Correct Answer Logic (Core)
Inside each question, add answer choices via the Answers repeater. For each answer:
- Answer Label: The text displayed on the answer button.
- Is Correct: Check this box on exactly one answer per question to mark it as the correct choice. The module uses this flag to score the user and to visually reveal the right answer after selection.
- Explanation: Richtext field that appears after the user picks an answer — but only on the correct answer item. Write a brief explanation of why this answer is correct. This field is only visible in the editor when Is Correct is enabled for that answer.
⚠️ CRITICAL RULE: One correct answer per question
Mark exactly one answer as correct in each question. If no answer is marked correct, the question cannot be scored. If multiple answers are marked correct, only the first one found will be treated as correct.
- ✅ Correct: one answer with Is Correct checked.
- ❌ Error: zero answers with Is Correct checked — question will break scoring.
- ❌ Error: two or more answers with Is Correct checked — unpredictable behavior.
3. Results & Ranges
This section controls what the user sees after completing all questions and submitting the lead capture form.
3.1 Result Ranges
Create one range item for every possible score band. Each range contains:
- Result Heading: The headline shown on the result screen (e.g., "Expert Level!", "Good Effort!").
- Min Score / Max Score: The inclusive lower and upper bounds of correct answers that trigger this result (e.g., Min:
4, Max: 5 for a 5-question quiz).
- Result Description: Richtext body text for the result screen. Use this to elaborate on the score, recommend next steps, or promote a relevant offer.
- CRM Property Value: A short machine-readable tag that identifies this result range. Use lowercase letters and underscores only (e.g.,
expert, intermediate, beginner).
What is CRM Property Value — and how is it different from Result Heading?
This is the most commonly misunderstood field in the module. Here is the distinction:
- Result Heading is what the user sees on screen (e.g., "Excellent! You're a trivia master.").
- CRM Property Value is what gets written into your HubSpot CRM for that contact (e.g.,
expert).
Why a separate machine-readable tag? Because CRM automation tools work best with short, stable, lowercase identifiers — not display strings:
- HubSpot Workflows: trigger enrollments when
trivia_quiz_result is equal to expert.
- Active Lists: segment contacts by their result category for targeted follow-up emails.
- Lead Scoring: assign score points to contacts based on their result tier.
- Social Sharing: the value is appended as a
?result= URL parameter so each shared link loads the correct result screen.
Example mapping for a 5-question quiz:
| Result Heading |
Score Range |
CRM Property Value |
| Keep Learning! |
0 – 1 |
beginner |
| Good Job! |
2 – 3 |
intermediate |
| Excellent! |
4 – 5 |
expert |
⚠️ Cover every possible score
Make sure your ranges together cover every score from 0 to the total number of questions, with no gaps. If a user's score falls outside all defined ranges, no result will be shown.
- ✅ For a 5-question quiz: ranges 0–1, 2–3, 4–5 — full coverage.
- ❌ Ranges 1–2 and 4–5 — a score of 0 or 3 has no match.
3.2 Results Page Interface
Configure the static labels on the result screen:
- Results Title: A prefix label displayed before the matched range heading (e.g., "Your Result: " → renders as "Your Result: Expert Level!").
- Share Button Text: Label for the social share button (e.g., "Share results").
- Retake Button Text: Label for the quiz reset button (e.g., "Retake quiz").
3.3 Dynamic Social Sharing
Enable the Enable Dynamic Sharing toggle to activate per-result Open Graph metadata. When enabled, a Social Share Content sub-section appears inside each result range item:
- OG Title: The link preview headline (e.g., "I scored Expert on this trivia quiz!").
- OG Description: The link preview subtext (e.g., "Take the quiz and test your knowledge!").
- OG Image: The link preview image.
When a user shares their result, the module appends ?result=<crm_property_value> to the page URL. On page load, if this parameter is detected, the module inject the matching range's OG tags into the page <head> automatically using HubSpot's head injection mechanism, overriding the default page meta for social crawlers.
Note: Most social platforms (LinkedIn, Facebook, Twitter) prioritize the last matching OG tag in the document, so the injected tags take precedence over the page's default meta tags even if duplicates appear in the source.
4. Lead Capture Form
This section configures the gate screen where users enter their contact details before seeing their results.
4.1 Form Requirements (Preparation)
Before configuring the module, create a standard Embedded Form in HubSpot and add the following fields to it:
- Email (Required — always present).
- First name / Last name / Phone (Optional, add only if you enable these fields in the module).
- Custom Property for Quiz Result (Required for CRM Sync — see Section 6).
- Custom Property for Answers Breakdown (Required for CRM Sync — see Section 6).
Important: HubSpot only saves data for properties that exist on the form. If a property is not added to the form in the HubSpot editor, the quiz data will be silently dropped — even if everything else is configured correctly.
4.2 HubSpot Form ID (GUID)
Paste the unique ID of the form created in step 4.1 into the Form ID field.
- Where to find it: Go to HubSpot → Marketing → Forms. Open your form. The GUID appears in the browser URL or in the "Embed Code" panel. It is a UUID string in the format
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
- EU Region: If your HubSpot account is on the EU1 data center, enable the HubSpot Region: EU checkbox. This routes form submissions to
api.hsforms.com/submissions/v3/…/eu1 endpoint.
4.3 Lead Capture Screen Labels
Customize the text shown on the gate screen:
- Form Title: Headline above the form (e.g., "Almost There!").
- Form Description: Richtext subtext below the title (e.g., "Enter your details to reveal your score.").
- Submit Button Text: Label for the submission button (e.g., "Get My Results").
4.4 Form Fields
The Email field is always present and cannot be disabled. For optional fields (First name, Last name, Phone number), each has its own sub-group with three settings:
- Enabled: Toggle to show or hide the field entirely.
- Required: Makes the field mandatory before submission (only visible when the field is enabled).
- Label / Placeholder: Customize the field label and placeholder text.
4.5 Data Privacy & Consent
Enable the Privacy Consent toggle to display a GDPR consent checkbox on the form. When enabled:
- Consent Text: Richtext field for your privacy statement or consent copy.
- Required: When checked, the user must accept before submitting.
Consent data is included in the HubSpot form submission as a legal basis entry, consistent with HubSpot's GDPR tools.
5. UI Settings & Labels
General interface behavior and translatable label strings.
- Progress Indicator Type: Choose between two styles:
- Progress Bar: A continuous fill bar that grows with each completed question.
- Numbered List: A horizontal list of numbered step dots, with active and answered states.
- Show Step Counter: Toggle a "1 / 5"-style counter above the current question. Works in both progress indicator modes.
- Back Button Text: Label for the previous-step button (e.g., "Back").
- Next Button Text: Label for the advance button (e.g., "Next").
- Error Message: Text shown when the user tries to advance without selecting an answer (e.g., "Please select an answer to continue.").
- Enable Session Storage: When enabled, quiz progress (current step and all answers given so far) is saved to the browser's
sessionStorage. If the user refreshes or navigates away and returns within the same browser session, they resume exactly where they left off. Disable this setting if you always want the quiz to start from the beginning.
6. CRM Data Sync
Configure how quiz results are written to HubSpot contact properties after form submission.
How the data chain works
Understanding the relationship between the three key identifiers will save you from the most common configuration mistakes:
- CRM Property Value (set per result range in Section 3) — the value that will be stored. Defined by you per range (e.g.,
expert).
- Result Property (set in this section) — the Internal Name of the HubSpot contact property where that value is stored (e.g.,
trivia_quiz_result).
- Answers Property (set in this section) — the Internal Name of the property where the full question-by-question breakdown is stored (e.g.,
trivia_quiz_answers).
At the moment of form submission, the module sends the following data to HubSpot Forms API:
{ name: "trivia_quiz_result", value: "expert" } — the matched range's CRM Property Value, written into the Result Property.{ name: "trivia_quiz_answers", value: "1. What is... → Jupiter (✓)
2. ..." } — the full answers breakdown, written into the Answers Property.
ℹ️ Note: the numeric score is not synced to CRM
The module writes the result category (e.g., expert) and the full answers breakdown to the CRM — but not the raw numeric score (e.g., "4 out of 5"). If you need the numeric score stored as well, create a third custom property and contact us for a customization.
Settings
- Enable CRM Sync: Master toggle for the feature. When disabled, only the standard form fields (email, name, phone) are submitted — no quiz data is passed to the CRM.
- Result Property: The Internal Name of the HubSpot contact property that will receive the matched range's CRM Property Value.
- This must be a property you create in HubSpot — see Section 4.1.
- Recommended type: Single-line text.
- Default value in the module:
trivia_quiz_result — you can keep this name or choose your own, but the name here must match the Internal Name of the property on your form exactly.
- Answers Property: The Internal Name of the property that will receive the full answers breakdown — each question with the selected answer and a correct/incorrect indicator.
- Recommended type: Multi-line text.
- Default value in the module:
trivia_quiz_answers.
- Answers Format: Controls how the answers breakdown is formatted before being stored:
- Readable: Plain text, one entry per question:
1. What is the largest planet?
→ Jupiter (✓)
2. What is H₂O?
→ Water (✓)
Best for human review directly in the HubSpot contact timeline.
- JSON: Structured array of objects with
question, answer, and correct keys. Best for use in webhooks, custom integrations, or programmatic processing.
Note: Property Internal Names must use lowercase letters, numbers, and underscores only, and must start with a letter (e.g., trivia_quiz_result). The same names must be added to your HubSpot Form as fields — see Section 4.1.
7. Advanced Settings
Optional settings for developers and power users. Not required for standard quiz operation.
- Custom CSS Class: Adds a custom class to the module's root wrapper
<div>. Use this to target the quiz with external CSS without modifying the module source.
- Custom ID: Assigns a custom
id attribute to the root element. Useful for anchor links (e.g., #my-quiz) or JavaScript targeting.
- Note: IDs must be unique per page. Do not reuse the same ID if placing multiple quiz instances on one page.
- Force Demo Data (Preview Mode): When enabled, the module ignores all content you've entered and loads a built-in demo quiz (5 questions, 3 result ranges) so you can preview the full quiz flow and visual style without filling in any fields.
- Note: In this mode, form submission is simulated — no contact or data is sent to HubSpot.
- Important: Always disable Force Demo Data before publishing to production.
PART 2. DESIGN & STYLE
The module uses a token-based Design System. All visual settings are defined once and propagate as CSS custom properties (--tsq-*) scoped to the module instance — no CSS overrides needed.
1. Typography
- Base Font Size: Sets the root font size for the entire quiz card.
- Small: 14px — compact, information-dense.
- Medium: 16px — default, works for most contexts.
- Large: 18px — better readability for accessibility-focused pages.
- Font Weight: Controls the default text weight across the module.
- Regular (400): Lightweight, editorial feel.
- Medium (500): Balanced — recommended for most designs.
- Semibold (600): Strong, assertive tone.
- Heading Scale Ratio: Determines the size contrast between headings and body text.
- Low (1.125): Subtle hierarchy, document-style layout.
- Medium (1.25): Default — balanced and versatile.
- High (1.5): Expressive, editorial-style headings.
2. Layout & Spacing
- Section Spacing: Vertical padding (top and bottom) for the module's outer wrapper — None, Small, Medium, or Large.
- Module Max Width: Limits the width of the quiz card. Adjustable from 400px to 1200px in 10px increments. Default: 800px. The card is always centered within the section.
- UI Density (Base Spacer): Controls the global internal spacing rhythm — gaps between elements, padding inside cards, and button heights.
- Compact (0.75rem): Tighter layout, mobile-app feel.
- Normal (1rem): Default balanced spacing.
- Spacious (1.5rem): More whitespace, larger touch targets.
- Fullscreen Mode: When enabled, the quiz card expands to fill the full viewport height and width, creating a distraction-free, immersive experience. Useful for dedicated quiz landing pages.
Mobile-First Logic: All spacing and font sizes automatically scale down on screens narrower than 600px. Answer buttons stack vertically and the social share menu expands to full width on mobile.
3. Colors
- Primary Color: Used for buttons, progress bar fill, active answer states, and interactive highlights. Inherits from the active HubSpot theme's primary color by default.
- Text on Primary: Text color inside primary-colored buttons. Set to white by default — adjust if using a light primary color. Inherits from the theme's secondary color.
- Card Background: Background color of the quiz card container.
- Text Color: Default body text color throughout the module. Inherits from the theme's primary color.
- Section Background: Background of the full-width module row. Set to fully transparent (
#ffffff at 0% opacity) by default, so the page background shows through.
Note: Correct answer feedback uses a fixed green color and incorrect feedback uses a fixed red color. These are intentional UX signals and are not overridable via the style settings.
4. Shape & Geometry
- Corner Rounding (Border Radius): Applies to the card, buttons, progress bar, and input fields. Value in pixels (e.g.,
8). Set to 0 for a sharp, square look.
- Shadow Intensity: Preset drop-shadow styles for the quiz card.
- Flat: No shadow — works well with bordered or colored section backgrounds.
- Soft & Modern: Subtle diffuse shadow — default, suits most designs.
- Hard / Retro: Offset solid shadow — bold, graphic style.
- Border Style: Adds a border around the quiz card.
- None: No border.
- Thin (1px): Subtle outline.
- Thick (2px): Strong outline.
- Border Color: Visible only when Border Style is set to Thin or Thick. Default:
#ededed.
Pre-Launch Checklist
- ✅ Every question has exactly one answer marked as Is Correct.
- ✅ Result ranges cover all possible scores from 0 to the total number of questions, with no gaps.
- ✅ CRM Property Values in result ranges use lowercase letters and underscores only (e.g.,
expert, beginner).
- ✅ Custom contact properties are created in HubSpot — Single-line text for Result, Multi-line text for Answers.
- ✅ A HubSpot Embedded Form is created with Email, optional name/phone fields, and both custom properties added to it.
- ✅ The correct Form ID (GUID) is pasted into Section 4 of the module settings.
- ✅ Property Internal Names in Section 6 match the Internal Names of the properties on your HubSpot form exactly.
- ✅ If using the EU data center, the HubSpot Region: EU checkbox is enabled.
- ✅ Force Demo Data is disabled before publishing to production.
- ✅ If using Dynamic Social Sharing, each result range has its OG Title, Description, and Image filled in.
Useful Links (HubSpot Documentation)
