JoinQuiz

JoinQuiz is a WordPress plugin for building multi-step quizzes and collecting lead submissions directly in WordPress.

Features

• Visual quiz builder in the WordPress admin.
• Single-choice, multiple-choice, short text, long text, 1–10 scale, file upload, and contact form steps.
• Conditional branching between steps.
• Thank-you, result, and redirect final screens.
• Lead storage with status management, notes, analytics, and CSV export.
• Admin email notifications and optional visitor auto-replies through wp_mail().
• Optional webhook delivery with configurable methods, headers, body templates, retries through WP-Cron, and delivery logs.
• Consent checkbox support for contact forms.
• Custom colors, typography, border radius, and theme font inheritance.
• No account or third-party integration is required for the core plugin.

Requirements

• WordPress with administrator access.
• PHP 8.1 or newer.
• A WordPress installation with AJAX and WP-Cron available.

Installation

1. Download or clone this repository.
2. Copy or clone the repository directory into wp-content/plugins/ (the folder may be named joinquiz).
3. Activate JoinQuiz from Plugins in the WordPress admin.
4. Open JoinQuiz → Quizzes and create a quiz.
5. Add the shortcode shown in the quiz list to a page or post:

[joinquiz id="123"]

Replace 123 with the ID of the quiz you want to display.

Creating a quiz

1. Open JoinQuiz → Quizzes → New Quiz.
2. Add and reorder steps.
3. Configure answer options, contact fields, and branching rules.
4. Configure the final screen shown after submission.
5. Save the quiz and copy its shortcode to a page or post.

Leads and notifications

Completed contact forms are stored as leads in WordPress. Administrators can review lead details, change statuses, add internal notes, inspect analytics, and export submissions to CSV.

Email templates support these tokens:

{name} {phone} {email} {quiz_title} {site_name} {date} {answers_summary} {lead_url}

Custom contact fields can be referenced as {field_key}.

Webhooks

Webhook delivery is optional and configured per quiz. Enter one endpoint per line, choose the HTTP method and content type, then define headers and the request body with placeholders.

Webhook requests are scheduled through WP-Cron after a lead is saved. A webhook failure does not prevent the lead from being stored. Delivery logging can be enabled per quiz and keeps the latest 50 requests.

Do not enable a webhook with real personal data until the endpoint, access controls, retention policy, and privacy notice have been reviewed.

Demo quiz

The repository includes a WP-CLI helper that creates a generic English demo quiz:

wp eval-file bin/seed-test-quiz.php --allow-root

The script removes an earlier demo quiz with the same title before creating a new one. Run it only in a development or staging environment.

Data and cleanup

JoinQuiz stores quiz definitions and lead records in WordPress, analytics events in the {prefix}jq_events table, and uploaded files in the uploads/joinquiz/ directory. The Advanced settings tab controls whether plugin data is deleted during a full uninstall.

Deactivating the plugin does not delete quiz, lead, or analytics data.

Development

The plugin uses PHP, vanilla JavaScript, and CSS. There is no build step required for the current version.

The admin/, includes/, and public/ directories separate administrator functionality, shared server-side logic, and frontend assets.

Scope

JoinQuiz is provided as a focused working example. Review security, privacy, email delivery, file-upload rules, and webhook access controls before using it on a production site.

Usage and copyright

This repository is published for portfolio and demonstration purposes only.

No license is granted to copy, modify, reuse, sublicense, or redistribute the code. All rights are reserved by the copyright holder. Contact the owner if you need permission for a specific use.