Skip to main content

Referral links for Django

Project description

Hype

A Django module that implements referral link logic.

Concepts

This library implements two models:

  • The ReferralLink. This object represents a user's referral link, or invitation link. It has a string identifier which allows the user to share their link as /ref/<refid>/.
  • The ReferralHit. This is an instance of a user (logged in or anonymous) actually following a referral link.

The Anonymous Cookie

When a ReferralLink is followed, a ReferralHit object is created. If the link was followed by a logged in user, that user will be available on the ReferralHit object as a foreign key. If the link was followed by an anonymous user, a cookie will be set on the user for future reference.

The cookie contains a random UUID which is set on the ReferralHit. At any time, you may get that cookie and, should the user log in, update all ReferralHit objects with that matching UUID. The library includes a middleware which will automatically do this for every logged in users, see hype.middleware.AnonymousReferralMiddleware.

Confirming Referrals

You may wish to implement a SuccessfulReferral model which is created when a user who previously followed a ReferralLink (and thus created a ReferralHit) actually completes whichever steps the referral system requires referred users to complete (for example: Register to the website, make their first purchase, post their first comment, ...).

The ReferralHit model also has a confirmed DateTimeField which you may use for this purpose.

Supporting Referral Links on Any URL

Implementers may find it useful to allow a referral on any URL. This is implemented in the hype.middleware.ReferralLinkMiddleware middleware, which looks at all GET requests and, should a valid referral link be present in the GET parameters, redirects to that referral link's URL with the next parameter set to the original URL, without the referral link present.

Example:

  • /accounts/signup/?ref=abc123def redirects to...
  • /ref/abs123def?next=/accounts/signup/ which redirects to...
  • /accounts/signup/, after creating a ReferralHit.

Setup and configuration

  1. Install via python -m pip install django-hype
  2. Add hype to your INSTALLED_APPS
  3. Include hype.urls in your URLs. Example: url(r"^ref/", include("hype.urls"))
  4. Add hype.middleware.AnonymousReferralMiddleware to your MIDDLEWARE. This is required to update referrals for anonymous users when they log in.
  5. (optional) Add hype.middleware.ReferralLinkMiddleware to your MIDDLEWARE. This is required if you want ?ref=... to redirect properly.

These steps are enough to start gathering referral information. You create a referral link, and watch the ReferralHit table fill up as users follow it.

In addition to having that data, you may want to "confirm" referrals. The ConfirmedReferral model is there as a convenience model to allow you to filter down the referral hits in question. Upon creating a ConfirmedReferral you may also want to do something else, such as crediting a user some points. The atomicity and idempotency of such events is left as an exercise for the reader.

License

This project is licensed under the MIT license. The full license text is available in the LICENSE file.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_hype-1.0.0.tar.gz (8.0 kB view details)

Uploaded Source

Built Distribution

django_hype-1.0.0-py3-none-any.whl (8.3 kB view details)

Uploaded Python 3

File details

Details for the file django_hype-1.0.0.tar.gz.

File metadata

  • Download URL: django_hype-1.0.0.tar.gz
  • Upload date:
  • Size: 8.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.2.2 CPython/3.10.8 Darwin/21.6.0

File hashes

Hashes for django_hype-1.0.0.tar.gz
Algorithm Hash digest
SHA256 7778999bef636e08f96103fb92bc78812197c7f2642d8435a0c7205581111a5e
MD5 e99f650fd30736ba793c19f946a3b585
BLAKE2b-256 fb85203255a95edd827a05c542dae811d621d6902abc5c209b65da75b7d1cbf6

See more details on using hashes here.

File details

Details for the file django_hype-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: django_hype-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 8.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.2.2 CPython/3.10.8 Darwin/21.6.0

File hashes

Hashes for django_hype-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9a809bb63dafc7bfb1c8ef4131a72330baf969b8de945a2c9c73c86a043b0722
MD5 aaff9683fcdf5566f67aa5a16f173582
BLAKE2b-256 f618bebdc69f0b5d45bd678bd3b8fbf5ca7f704656c11d1e2f7d95411b69d819

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page