Post Raffle

Overview

The Post Raffle feature allows content creators to organize giveaways and lotteries directly within their posts. This powerful engagement tool helps you build community, reward loyal readers, and increase interaction with your content.

Key Features

Flexible Participation Requirements

Set custom requirements for raffle participation:

• Like Requirement: Participants must like the post
• Comment Requirement: Participants must leave a comment
• Follow Requirement: Participants must follow you (coming soon)
• Credit Cost: Optionally require credits for participation
• Multiple Requirements: Combine requirements as needed

Multiple Draw Modes

Choose how and when winners are selected:

Scheduled Draw

• Set a specific date and time for automatic drawing
• System automatically draws winners at the scheduled time
• Ideal for time-limited promotions
• Winners are notified via email automatically

Manual Draw

• Draw winners whenever you're ready
• Full control over timing
• Perfect for flexible campaigns
• One-click drawing from the management panel

Participant Count Draw

• Automatically draw when reaching a target number of participants
• Great for "first X participants" style raffles
• No need to monitor participation manually
• Instant gratification for participants

Rich Prize Descriptions

Create compelling prize descriptions:

• Rich Text Editor: Use TipTap editor for formatted descriptions
• Images: Add prize photos to attract participants
• Multiple Winners: Select multiple winners for a single raffle
• Detailed Information: Include terms, conditions, and prize details

Display Options

Choose where your raffle appears:

• Top Position: Display at the beginning of your post
• Bottom Position: Display at the end of your post
• Strategic placement for maximum visibility

Creating a Raffle

Prerequisites

• You must have a published post in edit mode
• Post must exist before creating a raffle
• Only post authors can create raffles

Step-by-Step Guide

1. Open Your Post

   • Navigate to your post in the dashboard
   • Click to enter edit mode

2. Access Raffle Configuration

   • Click the gift icon (🎁) in the editor toolbar
   • Located between the Share and Settings buttons

3. Configure Prize Information

   • Enter a compelling prize title
   • Write detailed prize description using the rich text editor
   • Optionally add prize image URL
   • Set the number of winners

4. Set Participation Requirements

   • Toggle "Require Like" if participants must like the post
   • Toggle "Require Comment" if participants must comment
   • Set credit cost if you want to charge credits (0 for free)

5. Choose Draw Mode

   • Scheduled: Select date and time for automatic drawing
   • Manual: Draw winners manually at your convenience
   • Participant Count: Set target number of participants

6. Select Display Position

   • Choose "Top" to display raffle at the beginning of post
   • Choose "Bottom" to display raffle at the end of post

7. Create Raffle

   • Review all settings
   • Click "Create Raffle" button
   • Raffle is now active and visible to readers

Participating in a Raffle

For Readers

1. Find a Post with Raffle

   • Look for raffle display boxes in posts
   • Check top or bottom of the post

2. Review Requirements

   • Read prize description and requirements
   • Check what actions are needed (like, comment, credits)
   • View deadline or participant count progress

3. Meet Requirements

   • Like the post if required
   • Leave a comment if required
   • Ensure you have enough credits if cost is set

4. Join the Raffle

   • Click "Participate" or "Join Raffle" button
   • Confirm participation in the dialog
   • Credits will be deducted if applicable

5. Wait for Results

   • For scheduled raffles: Wait until the draw time
   • For manual raffles: Wait for author to draw
   • For count-based: Drawing happens when target is reached

6. Winner Notification

   • Winners receive email notification
   • Check your email inbox
   • Winner list is displayed on the post

Participation Rules

• Login Required: Must be logged in to participate
• One Entry Per User: Each user can only participate once per raffle
• Verification: System verifies all requirements before allowing participation
• Credit Deduction: Credits are deducted immediately upon participation
• Non-Refundable: Credit costs are not refunded if you don't win

Managing Raffles

Viewing Participants

1. Open your post with active raffle
2. Access raffle management panel
3. View list of all participants
4. See participant details and verification status

Manual Drawing

For manual draw mode:

1. Open raffle management panel
2. Click "Draw Winners" button
3. System randomly selects winners
4. Winners are notified automatically via email

Updating Raffle

You can update certain raffle settings:

• Prize description and image
• Participation requirements
• Draw mode and settings
• Display position

Note: Cannot change after drawing is complete

Canceling Raffle

If needed, you can cancel an active raffle:

1. Open raffle management panel
2. Click "Cancel Raffle" button
3. Confirm cancellation
4. Raffle status changes to cancelled
5. No refunds for already spent credits

Winner Selection Process

Random Selection Algorithm

• Uses cryptographically secure random number generation
• Fisher-Yates shuffle algorithm ensures fairness
• Equal probability for all eligible participants
• Cannot be manipulated or predicted

Eligibility Verification

Before drawing, system verifies:

• User still meets all requirements
• Like status is current
• Comment exists and is valid
• Credit deduction was successful

Winner Notification

Winners are notified via email:

• Congratulatory message
• Prize details and description
• Instructions for claiming prize
• Contact information for prize distribution

Raffle Display

Active Raffle Display

When raffle is active, visitors see:

• Prize title and description
• Prize image (if provided)
• Participation requirements with icons
• Current participant count
• Time remaining (scheduled mode)
• Progress bar (participant count mode)
• "Participate" button

Completed Raffle Display

After drawing is complete:

• Prize information
• Winner list with avatars
• Total number of participants
• Draw completion date

For Non-Participants

• Can view raffle details
• Cannot see participant list
• Can still join if raffle is active

Credit System Integration

Credit Costs

• Set credit cost from 0 (free) to any amount
• Credits are deducted upon participation
• Must have sufficient credits to participate
• Credits are consumed immediately

Refund Policy

• No refunds for non-winners
• Credits spent are non-refundable
• Consider setting reasonable costs

For Free Raffles

• Set credit cost to 0
• All logged-in users can participate
• Still requires meeting other requirements (like, comment)

Automatic Drawing System

Scheduled Draws

• GitHub Actions cron job runs every 5 minutes
• Checks for raffles with past due draw time
• Automatically executes drawing
• Sends email notifications to winners
• Updates raffle status to "drawn"

System Requirements

• APP_URL environment variable must be set
• CRON_SECRET must be configured
• Email service must be operational
• Database connection must be active

Best Practices

Creating Effective Raffles

1. Clear Prize Description: Be specific about what winners receive
2. Realistic Requirements: Don't make participation too difficult
3. Fair Credit Costs: Consider your audience's credit availability
4. Appropriate Winner Count: Match prize quantity to participant expectations
5. Strategic Timing: Schedule draws for high-engagement periods

Boosting Participation

1. Attractive Prizes: Offer valuable or interesting prizes
2. Share Widely: Promote your raffle on social media
3. Clear Instructions: Make it easy to understand requirements
4. Engage Comments: Respond to participants' comments
5. Build Anticipation: Create excitement leading up to draw

Managing Winners

1. Timely Contact: Reach out to winners promptly
2. Clear Instructions: Explain how to claim prizes
3. Set Deadlines: Give winners a timeframe to claim
4. Alternative Winners: Have backup plan if winners don't respond
5. Public Announcement: Share winner announcement to build trust

Troubleshooting

Cannot Create Raffle

• Ensure you're in edit mode for an existing post
• Verify you're the post author
• Check that post is published
• Try refreshing the page

Participation Button Disabled

• Verify you're logged in
• Check if you've already participated
• Ensure you meet all requirements (like, comment)
• Verify you have enough credits

Winners Not Notified

• Check email service configuration
• Verify winner email addresses are valid
• Check spam folders
• Review cron job execution logs

Draw Not Happening Automatically

• Verify scheduled time is in the future
• Check GitHub Actions workflow is enabled
• Ensure CRON_SECRET is correctly set
• Wait at least 5 minutes after scheduled time

Security and Fairness

Anti-Fraud Measures

• One participation per user enforced by database constraints
• IP address logging for audit purposes
• Requirement verification before participation
• Secure random number generation for winner selection

Data Privacy

• Participant information is private
• Only post author can view participant list
• Winner list is public after drawing
• Email addresses are protected

Fair Play

• Cannot participate in your own raffles
• Cannot change requirements after participation begins
• Random selection cannot be influenced
• All participants have equal chances (within same raffle)

Limitations

Current Limitations

• Follow requirement not yet implemented
• Cannot edit prize after participants join
• No partial refunds if raffle is cancelled
• Maximum participants limited by database performance

Quota Limits

• Free plan: Limited raffles per month
• Pro plan: Higher raffle creation limit
• Lifetime plan: Unlimited raffles

Future Enhancements

Planned improvements:

• Follow requirement implementation
• Raffle templates for quick setup
• Advanced analytics and statistics
• Export participant lists
• Bulk winner contact tools
• Integration with more notification channels
• Raffle duplication feature

FAQ

Q: Can I run multiple raffles for the same post? A: Currently, one active raffle per post is supported.

Q: What happens if no one participates? A: Drawing won't proceed. You can cancel or extend the raffle.

Q: Can I change the winner count after creation? A: Yes, but only before any participants join.

Q: Are credits refunded if raffle is cancelled? A: No, credits are non-refundable once spent.

Q: How are winners selected? A: Using cryptographically secure random selection with Fisher-Yates algorithm.

Q: Can I manually notify winners? A: Yes, but automatic email is sent. You can also contact them separately.

Q: What if a winner doesn't respond? A: You'll need to manually contact them or select alternative winners.

Q: Can participants see who else joined? A: No, participant list is only visible to the post author.

Support

If you encounter issues or have questions:

• Check this documentation first
• Review the troubleshooting section
• Contact support via email
• Report bugs on GitHub issues page