{"id":31696601,"url":"https://github.com/kapildevpal/referral_box","last_synced_at":"2025-10-08T17:09:33.932Z","repository":{"id":306670620,"uuid":"1026916665","full_name":"KapilDevPal/Referral_box","owner":"KapilDevPal","description":"💎 A flexible Ruby gem to add loyalty points, dynamic tiers, and referral rewards to any Rails app. Track signups, clicks, and geolocation with zero setup.","archived":false,"fork":false,"pushed_at":"2025-08-29T08:14:11.000Z","size":101,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-08T04:26:15.617Z","etag":null,"topics":["gamification","loyalty-program","marketing","points-system","rails","referral-link","rewards","ruby-gem"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/referral_box","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KapilDevPal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-26T22:35:04.000Z","updated_at":"2025-09-17T12:30:16.000Z","dependencies_parsed_at":"2025-07-27T01:25:57.262Z","dependency_job_id":"a0fa378c-dec0-484b-b113-c898fdc0f560","html_url":"https://github.com/KapilDevPal/Referral_box","commit_stats":null,"previous_names":["kapildevpal/loyaltyref"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/KapilDevPal/Referral_box","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KapilDevPal%2FReferral_box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KapilDevPal%2FReferral_box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KapilDevPal%2FReferral_box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KapilDevPal%2FReferral_box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KapilDevPal","download_url":"https://codeload.github.com/KapilDevPal/Referral_box/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KapilDevPal%2FReferral_box/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278981518,"owners_count":26079640,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gamification","loyalty-program","marketing","points-system","rails","referral-link","rewards","ruby-gem"],"created_at":"2025-10-08T17:09:32.857Z","updated_at":"2025-10-08T17:09:33.920Z","avatar_url":"https://github.com/KapilDevPal.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ReferralBox 📦\n**PLEASE VISIT THIS**\nGEM BEEN Updated \nhttps://github.com/KapilDevPal/Referral_box\n\n\n![ChatGPT Image Jul 27, 2025, 05_45_46 PM](https://github.com/user-attachments/assets/5124228a-068d-4a41-a9ac-3e0c35739afc)\n\n\nA flexible Ruby gem for building loyalty and referral systems in Rails apps.\n\n* 🎁 Reward users with points based on their activity\n* 🧱 Create dynamic tier levels (Silver, Gold, Platinum)\n* 🤝 Add referral rewards with unique referral codes\n* 🔧 Fully customizable and configurable\n* 🎛️ Admin dashboard (ERB based)\n* 🔄 Supports any user model: `User`, `Customer`, `Account`, etc.\n\n---\n\n## 📚 Documentation\n\n- **[Quick Start Guide](QUICK_START.md)** - Get running in 5 minutes\n- **[Complete Documentation](DOCUMENTATION.md)** - Full developer guide with examples\n- **[API Reference](DOCUMENTATION.md#api-reference)** - All methods and options\n\n---\n\n## 🚀 Installation\n\n```ruby\n# Gemfile\ngem 'referral_box'\n```\n\n```bash\n$ bundle install\n$ rails generate referral_box:install\n$ rails db:migrate\n```\n\n---\n\n## 🛠️ Configuration\n\nCreate your configuration block in an initializer:\n\n```ruby\n# config/initializers/referral_box.rb\n\nReferralBox.configure do |config|\n  # Define which model represents your app's user/customer\n  config.reference_class_name = 'User' # or 'Customer', 'Account', etc.\n\n  config.earning_rule = -\u003e(user, event) do\n    # Example: earn 10 points per ₹100 spent\n    event.amount / 10\n  end\n\n  config.redeem_rule = -\u003e(user, offer) do\n    offer.cost_in_points\n  end\n\n  config.tier_thresholds = {\n    \"Silver\" =\u003e 500,\n    \"Gold\" =\u003e 1000,\n    \"Platinum\" =\u003e 2500\n  }\n\n  config.reward_modifier = -\u003e(user) do\n    case user.tier\n    when \"Silver\" then 1.0\n    when \"Gold\" then 1.2\n    when \"Platinum\" then 1.5\n    else 1.0\n    end\n  end\n\n  config.referral_reward = -\u003e(referrer, referee) do\n    ReferralBox.earn_points(referrer, 100)\n    ReferralBox.earn_points(referee, 50)\n  end\nend\n```\n\n---\n\n## ✅ Features\n\n### 🎁 Loyalty Program\n\n| Feature              | Description                   |\n| -------------------- | ----------------------------- |\n| Points system        | Earn points via config lambda |\n| Custom earning rules | Define rules per event/user   |\n| Redeem points        | Redeem points for offers      |\n| Manual adjustment    | Admins can modify balances    |\n| Points expiration    | e.g. 90 days                  |\n| Transaction logging  | All activity is logged        |\n| Check balance        | Easy method to check          |\n\n### 🧱 Tier System (Dynamic)\n\n| Feature                 | Description                 |\n| ----------------------- | --------------------------- |\n| Dynamic definitions     | e.g. Silver =\u003e 500 points   |\n| Auto tier assignment    | Based on balance            |\n| Callbacks on promotion  | `on_tier_changed` hook      |\n| Reward modifier by tier | e.g. Gold users get +20%    |\n| DB persistence          | Can store or calculate tier |\n\n### 🤝 Referral System\n\n| Feature               | Description                                                   |\n| --------------------- | ------------------------------------------------------------- |\n| Unique referral codes | Auto-generated or custom                                      |\n| ?ref=code tracking    | Via signup links                                              |\n| Multi-level referrals | Parent/child tree                                             |\n| Referral rewards      | Custom logic supported                                        |\n| Referral analytics    | Track clicks, accepted signups, geo-location, and device type |\n\n### ⚙️ Core Gem Features\n\n* Developer config block\n* Extensible models\n* Simple public API: `earn_points`, `redeem_points`, `balance`, `track_referral`\n* Rails generators for setup\n* Support for any user model (User, Account, Customer, etc.)\n\n### 🖥️ Admin UI\n\n* Mountable engine with ERB templates\n* Routes like `/referral_box`\n* Views to list users, transactions, referrals\n\n---\n\n## 🔮 Future Scope\n\n### 📊 Analytics \u0026 Admin\n\n* Leaderboards by points\n* Referral tree visualizer\n* ActiveAdmin / custom dashboard\n* Export CSV/JSON of logs\n\n### 🔔 Engagement\n\n* Email / in-app notifications\n* Badges based on milestones\n* Activity calendar\n* Social sharing for referral links\n\n---\n---\n\n## 🧪 Usage Examples\n\n```ruby\n# Earn points\nReferralBox.earn_points(current_user, event: order)\n\n# Redeem points\nReferralBox.redeem_points(current_user, offer: coupon)\n\n# Check balance\nReferralBox.balance(current_user)\n\n# Track referral\nReferralBox.track_referral(ref_code: params[:ref])\n```\n\n---\n\n## 📬 Contribution\n\nPRs are welcome 🙌 — help improve the gem or suggest features.\n\n## 📜 License\n\nMIT © 2025 Kapil Dev Pal(Rails To Rescue) \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkapildevpal%2Freferral_box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkapildevpal%2Freferral_box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkapildevpal%2Freferral_box/lists"}