{"id":15180641,"url":"https://github.com/hearthsim/django-reflinks","last_synced_at":"2025-10-01T22:31:16.290Z","repository":{"id":57421530,"uuid":"111783238","full_name":"HearthSim/django-reflinks","owner":"HearthSim","description":"Referral links implementation for Django","archived":true,"fork":false,"pushed_at":"2022-05-13T00:03:34.000Z","size":40,"stargazers_count":15,"open_issues_count":4,"forks_count":5,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-12-29T03:08:02.985Z","etag":null,"topics":["django"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/HearthSim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-23T08:28:36.000Z","updated_at":"2023-11-04T12:39:57.000Z","dependencies_parsed_at":"2022-09-10T13:21:00.636Z","dependency_job_id":null,"html_url":"https://github.com/HearthSim/django-reflinks","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HearthSim%2Fdjango-reflinks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HearthSim%2Fdjango-reflinks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HearthSim%2Fdjango-reflinks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HearthSim%2Fdjango-reflinks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HearthSim","download_url":"https://codeload.github.com/HearthSim/django-reflinks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234908926,"owners_count":18905500,"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":["django"],"created_at":"2024-09-27T16:40:15.148Z","updated_at":"2025-10-01T22:31:15.961Z","avatar_url":"https://github.com/HearthSim.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django Reflinks\n\n[![Build Status](https://api.travis-ci.org/HearthSim/django-reflinks.svg?branch=master)](https://travis-ci.org/HearthSim/django-reflinks)\n\nA Django module that implements referral link logic.\n\n\n## Concepts\n\n\nThis library implements two models:\n\n- The `ReferralLink`. This object represents a user's referral link, or invitation link.\n  It has a string identifier which allows the user to share their link as `/ref/\u003crefid\u003e/`.\n- The `ReferralHit`. This is an instance of a user (logged in or anonymous) actually following\n  a referral link.\n\n## The Anonymous Cookie\n\nWhen a ReferralLink is followed, a `ReferralHit` object is created. If the link was followed\nby a logged in user, that user will be available on the ReferralHit object as a foreign key.\nIf the link was followed by an anonymous user, a cookie will be set on the user for future\nreference.\n\nThe cookie contains a random UUID which is set on the ReferralHit. At any time, you may get\nthat cookie and, should the user log in, update all ReferralHit objects with that matching\nUUID.\nThe library includes a middleware which will automatically do this for every logged in users,\nsee `django_reflinks.middleware.AnonymousReferralMiddleware`.\n\n\n## Confirming referrals\n\nYou may wish to implement a `SuccessfulReferral` model which is created when a user who\npreviously followed a `ReferralLink` (and thus created a `ReferralHit`) actually completes\nwhichever steps the referral system requires referred users to complete (for example:\nRegister to the website, make their first purchase, post their first comment, ...).\n\nThe `ReferralHit` model also has a `confirmed` DateTimeField which you may use for this purpose.\n\n\n## Supporting referral links on any URL.\n\nImplementers may find it useful to allow a referral on any URL. This is implemented in the\n`django_reflinks.middleware.ReferralLinkMiddleware` middleware, which looks at all GET requests\nand, should a valid referral link be present in the GET parameters, redirects to that referral\nlink's URL with the `next` parameter set to the original URL, without the referral link present.\n\nExample:\n - `/accounts/signup/?ref=abc123def` redirects to...\n - `/ref/abs123def?next=/accounts/signup/` which redirects to...\n - `/accounts/signup/`, after creating a ReferralHit.\n\n\n## Setup and configuration\n\n1. Install django-reflinks\n2. Add `django_reflinks` to your `INSTALLED_APPS`\n3. Include `django_reflinks.urls` in your urls. Example: `url(r\"^ref/\", include(\"django_reflinks.urls\"))`\n4. Add `django_reflinks.middleware.AnonymousReferralMiddleware` to your `MIDDLEWARE`.\n   This is required to update referrals for anonymous users when they log in.\n5. (optional) Add `django_reflinks.middleware.ReferralLinkMiddleware` to your `MIDDLEWARE`.\n   This is required if you want `?ref=...` to redirect properly.\n\nThese steps are enough to start gathering referral information.\nYou create a referral link, and watch the `ReferralHit` table fill up as users follow it.\n\nIn addition to having that data, you may want to \"confirm\" referrals. The `ConfirmedReferral`\nmodel is there as a convenience model to allow you to filter down the referral hits in question.\nUpon creating a ConfirmedReferral you may also want to do something else, such as crediting a\nuser some points.\nThe atomicity and idempotency of such events is left as an exercise for the reader.\n\n\n## License\n\nThis project is licensed under the MIT license. The full license text is\navailable in the LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhearthsim%2Fdjango-reflinks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhearthsim%2Fdjango-reflinks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhearthsim%2Fdjango-reflinks/lists"}