Activity Hooks

Headless hooks for interactive activities: quizzes, spin wheels, forms, polls, and surveys.

Every activity hook follows the same pattern: accept a config (from useEngagementData), manage interaction state locally, submit to the server on completion, and return actionResults with points awarded, badges unlocked, rewards claimed, and challenge progress.

useQuiz

Full quiz state, question navigation, answer tracking, client-side scoring, and server-side action execution.

const quiz = useQuiz({
  engagementId: 'YOUR_UUID',
  activityId: 'QUIZ_COMPONENT_ID',
  config: quizConfig,  // from useEngagementData().getQuizConfig()
});

// Navigation
quiz.currentQuestion    // { question: string, options: string[], ... }
quiz.currentIndex       // number (0-based)
quiz.totalQuestions     // number
quiz.isFirstQuestion    // boolean
quiz.isLastQuestion     // boolean
quiz.progress           // number (0-100)
quiz.next()             // Go to next question
quiz.previous()         // Go to previous question
quiz.goTo(index)        // Jump to specific question

// Answers
quiz.selectedAnswer     // number | null (selected option index)
quiz.answers            // (number | null)[] (all answers)
quiz.selectAnswer(i)    // Select an option

// Submission
quiz.submit()           // Submit answers (async, calls server)
quiz.isSubmitting       // boolean

// Results (after submit)
quiz.isComplete         // boolean
quiz.score              // { score, maxScore, percentage, passed }
quiz.feedback           // { title, message } (performance-based)
quiz.actionResults      // Server results: points, badges, rewards
quiz.reset()            // Reset for retry

useSpinWheel

Two-step spin flow: call spin() to get the result from the server, animate your wheel to the target angle, then call confirmResult() to record the completion.

const wheel = useSpinWheel({
  engagementId: 'YOUR_UUID',
  activityId: 'WHEEL_COMPONENT_ID',
  config: spinWheelConfig,
});

// State
wheel.segments          // SpinWheelSegment[], segment labels, colors, weights
wheel.isSpinning        // boolean
wheel.result            // SpinWheelResult | null (after spin)
wheel.rotation          // number, target rotation degrees for CSS animation
wheel.actionResults     // Server results after confirmResult()

// Actions
await wheel.spin()      // Call server, get result + target rotation
await wheel.confirmResult() // After animation ends, record completion
wheel.reset()           // Reset for another spin

Animation tip: Use wheel.rotation with a CSS transform: rotate() transition. Call wheel.confirmResult() in the onTransitionEnd callback.

useForm

Form field management with validation, touched tracking, and submission.

const form = useForm({
  engagementId: 'YOUR_UUID',
  activityId: 'FORM_COMPONENT_ID',
  config: formConfig,
});

// Fields
form.fields             // FormField[], field definitions (label, type, required, etc.)
form.values             // Record<string, unknown>, current values
form.errors             // Record<string, string>, validation errors
form.touched            // Record<string, boolean>, which fields have been touched

// State
form.isValid            // boolean, all fields pass validation
form.isSubmitting       // boolean
form.actionResults      // Server results after submit

// Actions
form.setValue(fieldId, value)  // Update a field value
form.setTouched(fieldId)      // Mark a field as touched (show validation)
form.validate()               // Run validation on all fields
form.submit()                 // Submit the form (async)
form.reset()                  // Reset all values

Validation: Built-in validators for email, phone, URL, and custom regex patterns. Validation runs automatically on touched fields and on submit.

usePoll

Single or multi-select poll with live results.

const poll = usePoll({
  engagementId: 'YOUR_UUID',
  activityId: 'POLL_COMPONENT_ID',
  config: pollConfig,
});

poll.question           // string
poll.options            // PollOption[], { id, label }
poll.selectedOptions    // string[], selected option IDs
poll.isMultiSelect      // boolean
poll.isSubmitted        // boolean
poll.results            // PollResults | null, vote counts per option
poll.actionResults      // Server results

poll.select(optionId)   // Toggle an option
poll.submit()           // Submit votes
poll.reset()            // Reset

useSurvey

Multi-question survey with navigation and progress tracking.

const survey = useSurvey({
  engagementId: 'YOUR_UUID',
  activityId: 'SURVEY_COMPONENT_ID',
  config: surveyConfig,
});

survey.questions         // SurveyQuestion[]
survey.currentIndex      // number
survey.totalQuestions    // number
survey.progress          // number (0-100)
survey.responses         // Record<string, unknown>
survey.isComplete        // boolean
survey.isSubmitting      // boolean
survey.actionResults     // Server results

survey.setResponse(questionId, value)
survey.next()
survey.previous()
survey.submit()
survey.reset()