{"id":13877894,"url":"https://github.com/excid3/refer","last_synced_at":"2025-05-15T09:03:51.210Z","repository":{"id":243900513,"uuid":"813719262","full_name":"excid3/refer","owner":"excid3","description":"Referral codes for Ruby on Rails applications","archived":false,"fork":false,"pushed_at":"2025-05-08T15:17:26.000Z","size":188,"stargazers_count":282,"open_issues_count":2,"forks_count":13,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-15T09:02:57.201Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/excid3.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"MIT-LICENSE","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},"funding":{"github":["excid3"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2024-06-11T15:50:59.000Z","updated_at":"2025-05-14T15:37:14.000Z","dependencies_parsed_at":"2024-06-11T23:23:57.032Z","dependency_job_id":"4cf14ad6-e71f-4892-b892-11e3cc8bb0b1","html_url":"https://github.com/excid3/refer","commit_stats":null,"previous_names":["excid3/referral_codes"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Frefer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Frefer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Frefer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Frefer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/excid3","download_url":"https://codeload.github.com/excid3/refer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310513,"owners_count":22049468,"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","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":[],"created_at":"2024-08-06T08:01:34.261Z","updated_at":"2025-05-15T09:03:51.197Z","avatar_url":"https://github.com/excid3.png","language":"Ruby","funding_links":["https://github.com/sponsors/excid3"],"categories":["Ruby"],"sub_categories":[],"readme":"# Refer\n\nReferral codes and affiliate links for Ruby on Rails applications.\n\n## 📦 Installation\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"refer\"\n```\n\nAnd then execute:\n```bash\n$ bundle\n```\n\nAdd Refer to your controllers to store referral cookies:\n```bash\nbin/rails generate refer:install\n```\n\nAnd add Refer to your model:\n```bash\nbin/rails generate refer:model User\nbin/rails db:migrate\n```\n\n## 🧑‍💻 Usage\n\nRefer adds a model to your Rails application for tracking referrals and referral codes.\n\nTo track referrals, you'll need to\n\n1. Create a referral code\n2. Set a cookie with the referral code\n3. Create the referral\n4. (Optional) Provide a reward for successful referral\n\n##### Create a referral code\n\nYou can create referral codes through the association:\n\n```ruby\nuser.referral_codes.create #=\u003e randomly generated code\nuser.referral_codes.create(code: \"chris\")\n```\n\nTo customize the referral code generator:\n\n```ruby\nRefer.code_generator = -\u003e(referrer) { [referrer.id, SecureRandom.alphanumeric(8)].join(\"-\") }\n#=\u003e generates codes like \"1-7frb5fUw\"\n```\n\nBy default, Refer will generate 8 character alphanumeric codes.\n\n##### Set a referral cookie\n\nTo track users, we need to stash the referral code in a cookie when present. By default, Refer will look for `?ref=code` and save this in a cookie.\n\n```ruby\nclass ApplicationController \u003c ActionController::Base\n  set_referral_cookie\nend\n```\n\nMove `set_referral_cookie` to specific controllers if you'd only like cookies set in certain areas like marketing pages for example.\n\n```ruby\nclass MarketingController \u003c ActionController::Base\n  set_referral_cookie except: [:about_us]\nend\n```\n\nYou can customize the param name with:\n\n```ruby\nRefer.param_name = :ref\n```\n\nYou can customize the cookie name with:\n\n```ruby\nRefer.cookie_name = :refer_code\n```\n\n##### Refer a user:\n\nTo create a referral, you can run the following\n\n```ruby\nclass RegistrationsController \u003c ApplicationController\n  def create\n    @user = User.new(user_params)\n    if @user.save\n      refer @user #=\u003e Looks up cookie and attempts referral\n      redirect_to root_path\n    else\n      render :new, status: :unprocessable_entity\n    end\n  end\nend\n```\n\nYou can also do this manually:\n\n```ruby\nRefer.refer(code: \"referral_code\", referee: user)\n```\n\nRefer will make sure the user has not already been referred and create a Referral.\n\n##### Check if a user was referred already:\n\n```ruby\nRefer.referred?(user)\n#=\u003e true/false\n```\n\n##### Accessing Referrals\n\nTo access a user's referrals, you can use the `referrals` association:\n\n```ruby\nuser.referrals #=\u003e [Refer::Referral, Refer::Referral]\n```\n\nThis returns a list of `Refer::Referral` objects.\n\n##### Accessing Referral\n\nTo access a user's referral, you can use the `referral` association:\n\n```ruby\nuser.referral #=\u003e Refer::Referral\n```\n\nTo access a user's referrer, you can use `referrer`:\n```ruby\nuser.referrer #=\u003e User that referred this User\n```\n## Refer with Devise\n\nTo use Refer with Devise, you'll need to customize the Devise controller to track the referral after a successful registration.\n\nWe can do this by telling Devise to use a custom controller in the routes and hooking into the `create` action to track the referral.\n\n```ruby\n# config/routes.rb\ndevise_for :users, controllers: { registrations: \"users/registrations\" }\n```\n\n```ruby\n# app/controllers/users/registrations_controller.rb\nclass Users::RegistrationsController \u003c Devise::RegistrationsController\n  def create\n    super do\n      refer resource if resource.persisted?\n    end\n  end\nend\n```\n\n## Providing Referral Rewards\n\nThere are several common ways of handling rewards for successful referrals:\n\n* Immediate rewards\nWhen the referral is successfully created, you can immediately credit the referrer with their reward.\n\n* Reward after user actions\nYou can check if a user was referred after they complete the action and provide a reward to the referrer.\n\n* Time-based rewards\nTo provide a reward X days after a successful referral, you can use a schedule job to check for referrals X days ago and provide rewards to those referrers.\n\nWe recommend keeping records for each reward given to a referral so you can limit rewards.\n\n## Customizing Models\n\nYou can add features to Refer's models by using lazy load hooks.\n\n```ruby\n# config/initializers/refer.rb\nActiveSupport.on_load :refer_referral do\n  # Add features to Refer::Referral model\nend\n\nActiveSupport.on_load :refer_referral_code do\n  # Add features to Refer::ReferralCode model\nend\n\nActiveSupport.on_load :refer_visit do\n  # Add features to Refer::Visit model\nend\n```\n\n## 🙏 Contributing\nIf you have an issue you'd like to submit, please do so using the issue tracker in GitHub. In order for us to help you in the best way possible, please be as detailed as you can.\n\n## 📝 License\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcid3%2Frefer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexcid3%2Frefer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcid3%2Frefer/lists"}