Rewards program

The Rewards program turns passive bug reporters into engaged contributors. Every activity your users take in your app — navigating screens, submitting reports, leaving comments — earns them points. Points unlock tiers. Tiers unlock perks you configure: free plan upgrades, early-access flags, and (optionally) monetary payouts via Stripe Connect.

How the pipeline works

The identify() call is the gate. Until a user ID is known, activity events are buffered and tagged with the anonymous reporter_token_hash. As soon as identify() fires (typically on auth state change), the SDK flushes the buffer with the resolved user traits attached, and the server upserts an end_users record that links all future activity and reports to that identity.

Overview tab

The Overview tab shows a snapshot of your rewards program’s health:

The tiles are live — useRealtimeReload polls every 30 seconds via Supabase Realtime so you see activity without a page refresh.

Activity Rules tab

Rules define which user actions earn points and what the caps are.

Built-in defaults (set when the project first enables rewards):

Rules are applied by a PostgreSQL trigger (private.apply_activity_points) so the award is atomic and consistent regardless of which SDK surface fired.

Custom rules

Click + Add rule to create an action you define in your own code:

mushi.submitActivity([
  { action: 'lesson_complete', metadata: { lessonId: 'l_123', score: 0.9 } }
])

Then create a rule with action: 'lesson_complete', set the points, and it starts accruing immediately — no SDK update required.

Tier Ladder tab

Tiers map a point threshold to a named rank with optional perks.

Default ladder shipped with new projects:

Edit or extend the ladder to match your own program. Tier evaluation runs inside awardPointsForEndUser after every successful activity flush — if the new total crosses a threshold, a tier_up webhook fires automatically.

Contributors tab

A live leaderboard of your top reporters, ranked by total_points (descending). Filter by time window (7d / 30d / all-time) or search by display name / email.

Per-contributor drill-down (/v1/admin/rewards/contributors/:id) shows:

• Point history chart (daily breakdown)
• Each end_user_activity entry with the action, points awarded, and timestamp
• Linked reports with their classification status
• Current tier + progress to the next tier
• GDPR controls: export or delete the end-user’s data

Quests tab

Quests are multi-step goals. A user completes a quest by performing a defined sequence of actions within a time window.

Example quest — “First Feedback”:

1. session_start (day 0)
2. navigate to any 3 distinct screens (day 0–7)
3. report_submit or comment_add (day 0–14)

Quest completions award a bonus quest_complete point event in addition to the per-action awards.

Quest editor

Click + New quest to open the editor:

• Name and description (shown to users in the badge widget)
• Steps — drag-and-drop ordered list of { action, min_count, within_days }
• Reward points — awarded on completion
• Expiry — quest deadline (absolute date or rolling window)
• One-shot — whether a user can complete the same quest multiple times

Quest progress is evaluated server-side in evaluateQuestProgress after each activity flush, so no client-side code is needed to track completion state.

Retention tab

The Retention tab shows cohort-level analysis: how did the rewards program affect 7-day and 30-day retention for users who opted in versus those who did not?

Charts displayed:

• Retention curves: opted-in vs. opted-out cohorts
• Avg. sessions per user / week: rewards vs. control
• Report volume trend: did engagement translate to more reports?
• At-risk users: opted-in users who haven’t appeared in 14+ days (re-engagement candidates for a push campaign)

Data is computed by the intelligence-report edge function and cached in project_settings.retention_cache with a 24-hour TTL.

Simulator tab

The Simulator lets you preview how a point award would behave before you deploy it to users.

1. Pick or type an action name.
2. Enter an example userId (can be a test ID — no actual end_users row is created or modified).
3. Click Run — the server evaluates the rule, applies caps, and returns the award result, the capped reason if applicable, and the hypothetical new tier.

Use this to sanity-check multiplier interactions, daily cap edge cases, and quest trigger logic without touching production data.

Settings tab

Webhooks

Webhook payloads are sent for these events:

Register webhook endpoints in the Webhooks subtab, test-fire them with a synthetic payload, and view the delivery log.

Monetary payouts (P2)

When monetary payouts are enabled:

1. Each contributing user completes a Stripe Connect Express onboarding (linked from their profile or from a tier_up notification you send).
2. Your payout rules define a $/point rate and a minimum threshold.
3. The payout-aggregator cron job (runs monthly) computes each user’s earned amount, writes a reward_payouts row, and queues a Stripe transfer.
4. The Payout liability dashboard shows the outstanding liability (unpaid earned amounts) so you can top up your Stripe balance before month-end.

The JWT verification step (verifyUserToken in MushiRewardsConfig) ensures that monetary awards are only issued to authenticated users whose identity the host app can vouch for — preventing anonymous abuse.

GDPR & consent

The rewards pipeline stores:

User rights are handled by SDK endpoints:

If you use consentMode: 'explicit' (the default), the SDK surfaces a one-time prompt before the first identify() flush. The user’s choice is persisted server-side in end_users.opted_in, so it follows them across devices.