Engagement Hooks

Specialized hooks for loading engagement data, referral programs, contests, content gating, and activity tracking.

useEngagementData

Loads an engagement and provides typed accessors for component configs. This is the entry point — load your engagement first, then pass configs to activity hooks.

const {
  engagement,     // Full engagement object
  components,     // All components in the engagement
  isLoading,      // True while loading
  error,          // Error object if load failed

  // Typed config accessors
  getComponent,       // (type: string) => Component | null
  getComponentConfig, // <T>(type: string) => T | null
  getQuizConfig,      // () => QuizConfig | null
  getSpinWheelConfig, // () => SpinWheelConfig | null
  getFormConfig,      // () => FormConfig | null
  getPollConfig,      // () => PollConfig | null
  getSurveyConfig,    // () => SurveyConfig | null
} = useEngagementData({
  engagementId: 'YOUR_UUID',
});

useReferral

Referral code generation and tracking. Provides a shareable link, conversion stats, and clipboard support.

const referral = useReferral({
  participantId: 'user_123',
  campaignId: 'CAMPAIGN_UUID',     // optional
  refreshInterval: 60000,          // ms, default 60s
});

referral.code            // string | null — unique referral code
referral.shareUrl        // string | null — full shareable URL
referral.stats           // ReferralStats | null
                         //   { total_clicks, total_conversions, total_rewards_earned }
referral.isLoading       // boolean
referral.error           // Error | null
referral.refresh()       // Manual refresh
referral.copyLink()      // Copy share URL to clipboard — Promise<boolean>

useContest

Contest participation and leaderboard. Handles entry, rank tracking, prize tier visibility, and live score updates.

const contest = useContest({
  contestId: 'CONTEST_UUID',
  participantId: 'user_123',       // optional
  autoEnter: false,                // auto-enter on load
  refreshInterval: 30000,          // ms
  leaderboardLimit: 10,
});

contest.isEntered        // boolean
contest.entry            // ContestEntry | null
contest.myRank           // number | null
contest.leaderboard      // ContestLeaderboardEntry[]
contest.totalParticipants // number
contest.prizes           // ContestPrizeTier[]
contest.myPrizeTier      // ContestPrizeTier | null
contest.isLoading        // boolean
contest.error            // Error | null
contest.enter(data?)     // Enter contest — Promise
contest.refresh()        // Manual refresh

useGates

Content gating and unlock state. Check whether screens or content targets are locked based on gate rules (activity completion, points thresholds, badge requirements).

const gates = useGates({
  engagementId: 'YOUR_UUID',
  targetIds: ['screen-2', 'screen-3'], // optional
  autoCheck: true,                      // check on mount
  refreshInterval: 30000,
});

gates.response           // GateCheckResponse | null
gates.loading            // boolean
gates.error              // Error | null
gates.check()            // Re-check gates
gates.isGated(targetId)  // boolean — true if target is locked
gates.gateStatus(targetId) // GateTargetStatus — full status for target

useActivityProgress

Activity streak and heatmap data. Tracks daily completions over a lookback period for streak counters and calendar heatmap visualizations.

const progress = useActivityProgress({
  engagementId: 'YOUR_UUID',
  activityDefinitionId: 'ACTIVITY_UUID',
  days: 90,                         // lookback period
  refreshInterval: 60000,
});

progress.todayCompleted   // boolean
progress.todayValue       // number
progress.streak           // number — current streak
progress.longestStreak    // number
progress.completionRate   // number (0-100)
progress.entries          // HeatmapEntry[] — daily data for heatmap
progress.isLoading        // boolean
progress.error            // Error | null
progress.refresh()        // Manual refresh

useActivityCalendar

Daily activity log calendar. Provides a day-by-day view of activity completions for calendar-style UI components.

const calendar = useActivityCalendar({
  engagementId: 'YOUR_UUID',
  activityDefinitionId: 'ACTIVITY_UUID',
  days: 30,
  refreshInterval: 60000,
});

calendar.entries          // DailyLogEntry[]
calendar.streak           // number
calendar.todayCompleted   // boolean
calendar.completedDays    // number
calendar.totalDays        // number
calendar.completionRate   // number (0-100)
calendar.isLoading        // boolean
calendar.error            // Error | null
calendar.refresh()        // Manual refresh