Usage

Referral.create

This is the factory method that the create_referral view calls but can be called directly in case you needed to integrate in a different way with pinax-referrals.

For example, you might want to automatically give every user a referral code that is emailed to them upon signup. In this case, you could created a one to one relationshiop between their Profile and pinax-referrals' Referral and create a signal receiver for when the Profile is created that calls:

referral = Referral.create(
    user=profile.user,
    redirect_to=reverse("home")
)
profile.referral = referral
profile.save()

Then you could, in the welcome email that you send them upon signup render their referral url that they could forward on to other users:

{{ user.get_profile.referral.url }}

The only required parameter for Referral.create is redirect_to. If you don't specify a user it will be recorded as None. This can be useful if you wanted to attach a relationship between some object in your system to a referral that might not have a user associated with it.

You can also pass in an optional label kwarg to Referral.create if you wanted to allow your users to create and manage multiple referrals so that labeling them became important to keep track of them.

At runtime, you can append the redirect_to URL parameter to your referral URL to dynamically redirect to an alternate destination.

{{ user.get_profile.referral.url }}?redirect_to=/special/

The URL parameter used can be altered in your settings file.

Referral.record_response

The classmethod record_response will attempt to see if the current user or session has any previous responses to an initial referral and if so will then proceed to record the response action.

For example, say you want to record the fact that the user did some site activity after clicking on the referral link you tweeted and subsequently decided to register and login to the site:

from pinax.referrals.models import Referral


def my_view(request, **kwargs):
    ...
    referral_response = Referral.record_response(request, "SOME_ACTION")
    ...

In this case the referral_response will be None if the user on the request doesn't have any previously recorded referral responses. In addition, if the user has responded to more than one Referral code, then this will associate the activity with the most recent response.

In addition, this supports passing an options target keyward argument, if you wanted to record associations with specific objects. For example:

Referral.record_response(request, "SOME_ACTION", target=some_object)

This will record a generic foreign key to some_object that you can use elsewhere to identify activity from your referral at a deeper level than just based on the action label.

Referral.referral_for_request

This class method, will give you a referral object for the given request in case you needed to apply any business logic in your project. For example, to do any comparisons on the referral.target with another object you have in context for segmenting permissions or authorizations to make your referral system more fine grained.