← reference

Encouragement Drops System

Overview

The Encouragement Drops system allows users to send "drops" (encouragement messages, media links, or science tidbits) to other users in the Stream. Users earn bonus drops when recipients increase their engagement after receiving a drop.

Features

  • Three Drop Types:

    • 💬 Encouragement: Personal words of encouragement
    • 🎵 Media: Links to Spotify, SoundCloud, Suno, or YouTube content
    • 🔬 Science Tidbit: Science-backed facts that encourage action

  • Daily Allowance: Users receive a configurable number of drops per day (default: 5)

  • Drop Library: Approved templates users can choose from

  • Custom Drops: Users can create custom drops (limited per day)

  • Bonus Drops: Earn extra drops when recipients increase engagement

  • Engagement Tracking: Automatically detects when recipients create entries after receiving drops

Database Schema

Tables

  • drop_templates: Approved drop templates

    • Type, title, content
    • Media type and thumbnail (for media drops)
    • Approval status and usage count

  • user_drops: Daily drop allowance tracking

    • Daily allowance, drops used, bonus drops earned
    • Calculated total available

  • drops_sent: Records of all drops sent

    • Sender, recipient, drop type, content
    • Entry association
    • Engagement tracking and bonus drops awarded

  • drop_config: System configuration

    • Daily allowance
    • Bonus drops per engagement
    • Engagement window (hours)
    • Max custom drops per day

API Endpoints

User Endpoints

  • GET /api/encouragement-drops/my-drops - Get available drops for today
  • GET /api/encouragement-drops/templates - Get approved templates (optionally filtered by type)
  • POST /api/encouragement-drops/send - Send a drop to another user
  • GET /api/encouragement-drops/received - Get drops received by current user
  • GET /api/encouragement-drops/config - Get system configuration

Admin Endpoints

  • GET /api/encouragement-drops/admin/templates - Get all templates (including unapproved)
  • POST /api/encouragement-drops/admin/templates - Create new template
  • PUT /api/encouragement-drops/admin/templates/:id - Update template
  • DELETE /api/encouragement-drops/admin/templates/:id - Delete template
  • GET /api/encouragement-drops/admin/config - Get configuration
  • PUT /api/encouragement-drops/admin/config - Update configuration
  • POST /api/encouragement-drops/admin/process-engagement - Manually trigger engagement processing

Cron Endpoint

  • POST /api/encouragement-drops/cron/process-engagement - Process engagement checks (requires cron secret)

User Flow

  1. View Available Drops: User sees how many drops they have available today
  2. Choose Recipient: User hovers over an entry in Stream and clicks "Send Drop"
  3. Select Drop Type: Choose encouragement, media, or science tidbit
  4. Choose or Create:
    • Select from approved templates in library
    • Or create custom drop (limited per day)
  5. Send: Drop is sent, drops used count increases
  6. Engagement Tracking: System checks if recipient creates entries within engagement window
  7. Bonus Drops: If engagement increases, sender earns bonus drops

Engagement Tracking

The system tracks engagement by checking if recipients create any of the following within the engagement window (default: 24 hours) after receiving a drop:

  • Journal entries
  • Satisfaction entries
  • Action notes
  • Sleep entries

If engagement increases, the sender earns bonus drops (default: 2).

Admin Configuration

Accessible via Admin Panel → Encouragement Drops tab.

Configuration Options

  • Daily Allowance: Default number of drops per day (default: 5)
  • Bonus Drops Per Engagement: Drops awarded when recipient increases engagement (default: 2)
  • Engagement Window Hours: Hours after receiving drop to count as engagement (default: 24)
  • Max Custom Drops Per Day: Maximum custom drops a user can create per day (default: 3)

Template Management

  • Create, edit, and delete drop templates
  • Approve/unapprove templates (only approved templates are visible to users)
  • View usage statistics
  • Support for all three drop types

UI Components

Stream Integration

  • Drop Button: Appears in entry hover preview for other users' entries
  • Drop Sender Modal: Full-featured modal for selecting/creating and sending drops
  • Template Library: Browse and select from approved templates
  • Custom Drop Creation: Create personalized drops

Admin UI

  • Configuration Panel: Edit system-wide settings
  • Template Management: Full CRUD for drop templates
  • Usage Statistics: View template usage counts

Setup

1. Database Migration

Run the migration to create tables:

supabase migration up

Or manually run supabase/migrations/027_add_encouragement_drops.sql

2. Initial Configuration

Default configuration is inserted automatically. Admins can adjust via admin panel.

3. Create Initial Templates

Admins should create some approved templates for users to choose from:

  • Encouragement messages
  • Popular music tracks (Spotify/YouTube)
  • Science tidbits about health, motivation, etc.

4. Cron Job Setup

Set up a cron job to process engagement checks (recommended: hourly):

# Example cron job (runs every hour)
0 * * * * curl -X POST https://your-api.com/api/encouragement-drops/cron/process-engagement \
  -H "X-Cron-Secret: YOUR_SECRET"

Set ENCOURAGEMENT_DROPS_CRON_SECRET environment variable.

Best Practices

  1. Template Variety: Create diverse templates across all three types
  2. Regular Updates: Add new templates regularly to keep library fresh
  3. Engagement Monitoring: Review engagement rates to optimize bonus drop amounts
  4. User Education: Help users understand how to earn bonus drops
  5. Content Moderation: Review custom drops for appropriateness (future enhancement)

Future Enhancements

  • Drop Notifications: Notify users when they receive drops
  • Drop History: View all drops sent/received
  • Drop Analytics: Track which templates are most effective
  • Auto-Approval: Automatically approve drops from trusted users
  • Drop Reactions: Allow recipients to react to drops
  • Drop Sharing: Share drops across social media
  • AI-Generated Drops: Use AI to suggest personalized drops
ENCOURAGEMENT DROPS — Docs | HiveJournal