ReferralBox 📦

A flexible Ruby gem for building loyalty and referral systems in Rails apps.

• 🎁 Reward users with points based on their activity
• 🧱 Create dynamic tier levels (Silver, Gold, Platinum)
• 🤝 Add referral rewards with unique referral codes
• 🔧 Fully customizable and configurable
• 🎛️ Admin dashboard (ERB based)
• 🔄 Supports any user model: User, Customer, Account, etc.

---

📚 Documentation

• Quick Start Guide - Get running in 5 minutes
• Complete Documentation - Full developer guide with examples
• API Reference - All methods and options

---

🚀 Installation

# Gemfile
gem 'referral_box'

$ bundle install
$ rails generate referral_box:install
$ rails db:migrate

---

🛠️ Configuration

Create your configuration block in an initializer:

# config/initializers/referral_box.rb

ReferralBox.configure do |config|
  # Define which model represents your app's user/customer
  config.reference_class_name = 'User' # or 'Customer', 'Account', etc.

  config.earning_rule = ->(user, event) do
    # Example: earn 10 points per ₹100 spent
    event.amount / 10
  end

  config.redeem_rule = ->(user, offer) do
    offer.cost_in_points
  end

  config.tier_thresholds = {
    "Silver" => 500,
    "Gold" => 1000,
    "Platinum" => 2500
  }

  config.reward_modifier = ->(user) do
    case user.tier
    when "Silver" then 1.0
    when "Gold" then 1.2
    when "Platinum" then 1.5
    else 1.0
    end
  end

  config.referral_reward = ->(referrer, referee) do
    ReferralBox.earn_points(referrer, 100)
    ReferralBox.earn_points(referee, 50)
  end
end

---

✅ Features

🎁 Loyalty Program

Feature	Description
Points system	Earn points via config lambda
Custom earning rules	Define rules per event/user
Redeem points	Redeem points for offers
Manual adjustment	Admins can modify balances
Points expiration	e.g. 90 days
Transaction logging	All activity is logged
Check balance	Easy method to check

🧱 Tier System (Dynamic)

Feature	Description
Dynamic definitions	e.g. Silver => 500 points
Auto tier assignment	Based on balance
Callbacks on promotion	on_tier_changed hook
Reward modifier by tier	e.g. Gold users get +20%
DB persistence	Can store or calculate tier

🤝 Referral System

Feature	Description
Unique referral codes	Auto-generated or custom
?ref=code tracking	Via signup links
Multi-level referrals	Parent/child tree
Referral rewards	Custom logic supported
Referral analytics	Track clicks, accepted signups, geo-location, and device type

⚙️ Core Gem Features

• Developer config block
• Extensible models
• Simple public API: earn_points, redeem_points, balance, track_referral
• Rails generators for setup
• Support for any user model (User, Account, Customer, etc.)

🖥️ Admin UI

• Mountable engine with ERB templates
• Routes like /referral_box
• Views to list users, transactions, referrals

---

🔮 Future Scope

📊 Analytics & Admin

• Leaderboards by points
• Referral tree visualizer
• ActiveAdmin / custom dashboard
• Export CSV/JSON of logs

🔔 Engagement

• Email / in-app notifications
• Badges based on milestones
• Activity calendar
• Social sharing for referral links

---

---

🧪 Usage Examples

# Earn points
ReferralBox.earn_points(current_user, event: order)

# Redeem points
ReferralBox.redeem_points(current_user, offer: coupon)

# Check balance
ReferralBox.balance(current_user)

# Track referral
ReferralBox.track_referral(ref_code: params[:ref])

---

📬 Contribution

PRs are welcome 🙌 — help improve the gem or suggest features.

📜 License

MIT © 2025 Kapil Dev Pal(Rails To Rescue)