Persona Scoring Quiz — Complete User Guide
Version: 1.0
Overview
Persona Scoring Quiz is a comprehensive HubSpot module designed to build interactive, multi-step quizzes with complex scoring logic (persona/trait mapping) and seamless CRM integration.
Use Cases:
- Marketing quizzes and audience segmentation.
- Product value demonstration through personalized results.
- Lead Generation with rich contact profile enrichment.
How It Works (Technical Concept)
To configure this module correctly, it is important to understand how it handles data:
- The Quiz UI: The user interacts with a custom, polished interface designed within the module settings.
- Data Transport: A standard HubSpot Form is used "under the hood" strictly as a data receiver. Visually, the standard HubSpot form is replaced by the Quiz interface, but a valid Form ID is required to save contacts and answers to the CRM.
Settings Structure
The documentation follows the exact order of the module configuration groups:
- Intro Step
- Questions & Scoring
- Results & Profiles
- Lead Capture Form
- UI Settings & Labels
- CRM Data Sync
- Design System (Style Tab)
PART 1. CONTENT & LOGIC
1. Intro Step
The first screen of the quiz. Its goal is to explain the value proposition and encourage the user to start.
- Title: Main headline.
- Description: Introductory text.
- Start Button Text: Label for the button (e.g., "Start Quiz").
2. Questions & Scoring
This section defines the questions and the scoring logic.
2.1 Questions
For each question, you define:
- The Question text.
- Helper text (optional context).
- Is optional? — If enabled, the user can skip this question.
2.2 Answers & Trait Scores (Core Logic)
Each answer choice can assign points to one or multiple "Personas" (Traits).
What is a Trait Name?
This is a technical identifier for the result (e.g., analyst, driver, creative). It is used for scoring calculations, selecting the final result screen, and syncing data to the CRM.
Configuring Trait Scores:
Inside each answer, you add items to the "Trait Scores" list:
- Trait Name: The identifier (lowercase letters only).
- Score Points: The weight of the answer (e.g.,
1, 2, 5).
⚠️ CRITICAL RULE: Naming Consistency
The Trait Name used here must match the Result Key in the Results & Profiles section exactly.
- ✅ Correct:
analyst (in Question) matches analyst (in Profile).
- ❌ Error:
Analyst does not match analyst (case sensitivity).
- ❌ Error:
data_analyst does not match analyst (spelling).
3. Results & Profiles
This block controls the final screen displayed after the quiz is completed.
3.1 Results Display Mode
- Show only primary result: Displays only the winning profile.
- Show top 3 traits: Displays the winner plus a chart of the runner-ups.
- Show all traits: Displays a full breakdown of all scores.
3.2 Profiles
Create a profile for every possible result.
- Result Key: The technical ID (e.g.,
analyst). Must match the Trait Name from section 2.
- Display Name: The headline for the user (e.g., "You are an Analyst").
- Description: Detailed description of the result.
3.3 Social Sharing
If Enable Dynamic Social Sharing is checked, the module will inject result-specific Open Graph tags (og:title, og:description, og:image) into the page head.
Note: The module adds these tags after the standard HubSpot meta tags. While this may result in duplicate tags in the source code, most social media platforms prioritize the last tag found (ours) when generating the link preview. This ensures users share their specific result, not the generic page cover.
4. Lead Capture Form
This section configures the "Gate" screen (where users enter their email) and the technical connection to HubSpot.
4.1 Form Requirements (Preparation)
Before configuring the module, create a standard Embedded Form in HubSpot and add the following fields:
- Email (Required).
- Firstname / Lastname (Optional, if you wish to collect them).
- Custom Property for Result (Required for CRM Sync).
- Custom Property for Answers (Required for CRM Sync).
Important: If a property is not added to the form in the HubSpot editor, the data will not be saved, even if the API configuration is correct. HubSpot only accepts data for fields present in the form.
4.2 HubSpot Form ID (GUID)
Enter the unique ID of the form created in step 4.1.
- Where to find it: Go to HubSpot → Marketing → Forms. Open your form. Copy the ID from the URL or the "Non-HubSpot Forms" integration script. It is typically a UUID string (e.g.,
a1b2c3d4-1234-...).
4.3 Lead Capture Screen (Visuals)
Customize the screen presented before the result:
- Form Title: e.g., "One last step!"
- Description: e.g., "Enter your email to reveal your persona."
- Submit Button Text: e.g., "Get My Results".
- Privacy Policy: Options to enable GDPR consent text/checkboxes.
5. UI Settings & Labels
General interface and navigation settings.
- Show Progress Bar: Toggle the top progress indicator.
- Show Step Counter: e.g., "Question 1/5".
- Back / Next Button Labels: Text for navigation buttons.
- Selection Error Message: Alert text displayed if a user tries to proceed without selecting an answer.
6. CRM Data Sync
Configure how results are written to contact properties.
- Enable CRM Sync: Toggles the data saving feature.
- Final Trait Property: The Internal Name of the property to store the main result (Key).
- Recommended Type: Single-line text.
- Answers Property: The Internal Name of the property to store the detailed Q&A history.
- Recommended Type: Multi-line text.
- Answers Format:
- Readable: Plain text format (Question → Answer). Best for human review.
- JSON: Structured data format. Best for programmatic usage or integrations.
Note: Property Internal Names must contain lowercase letters and underscores only (e.g., persona_quiz_result).
7. Advanced Settings
This section contains advanced and optional settings intended for developers and power users. These options are not required for normal quiz operation but provide additional flexibility for customization, preview, and recovery scenarios.
- Custom CSS Class: Adds a custom class to the module's root container. Use this to apply external CSS rules without modifying the module’s source code.
- Custom ID: Assigns a custom HTML id attribute to the root container of the module. Useful for creating anchor links (e.g.,
#my-quiz) or targeting via JavaScript.
- Note: The ID must be unique on the page. Do not reuse the same ID for multiple quiz instances.
- Force Demo Data (Preview Mode): Enables a safe "Sandbox" environment. When checked, the module ignores your current content and settings and loads a fully functional demo quiz.
- Note: In this mode, form submission is simulated — no data is sent to HubSpot CRM.
- Important: Remember to disable this setting before publishing to production.
PART 2. DESIGN & STYLE
The module uses a modern Design System based on CSS tokens. Instead of manually styling every element, you control global rules.
1. Typography
- Base Font Size: Sets the foundation (Small / Medium / Large).
- Heading Scale Ratio: Determines the contrast between headings and body text.
- Low Contrast (1.125): Subtle, document-style.
- High Contrast (1.50): Expressive, editorial style.
2. Layout & Spacing
- Section Spacing: Vertical padding (top/bottom) for the module wrapper.
- Module Max Width: Limits the width of the quiz card.
- UI Density (Base Spacer): Controls the global "tightness" of the interface.
- Compact: Smaller gaps, denser layout (mobile-app feel).
- Spacious: More whitespace, larger touch targets.
Mobile-First Logic: All spacing and font sizes are adaptive. On mobile devices, margins and padding automatically shrink to maximize usable screen space.
3. Colors
- Primary Color: Used for buttons, progress bars, and active states.
- Text on Primary: Ensures readability on buttons.
- Card Background: The background color of the quiz container.
- Section Background: The background of the entire row (can be transparent).
4. Shape & Geometry
- Corner Rounding: Radius for buttons and cards.
- Shadow Intensity: Preset shadow styles (Flat / Soft / Hard).
- Border Style: Thickness and color of the card border.
Pre-Launch Checklist
- ✅ Trait Names match exactly between Questions (Scoring) and Results (Profiles).
- ✅ Custom Properties are created in HubSpot (Single-line for Result, Multi-line for Answers).
- ✅ A HubSpot Form is created, and the Email + Custom Properties are added to it.
- ✅ The correct Form ID is pasted into the module settings (Section 4).
- ✅ Property Internal Names are entered correctly in Section 6 (lowercase, no spaces).
Useful Links (HubSpot Documentation)
