Drupal 7 User Referral Module

A critical part of effective online marketing is knowing the sources of a website's successful traffic. Every business or other type of organization should be keenly interested in how people find their website, and which sources are sending the higher percentage of visitors who become customers, donors, or participants in some other manner. Conventional web traffic analytics can provide exact numbers on how many unique humans and Internet bots have visited which pages on which days, as well as which external links and search engines provided traffic. But they typically do not track which users could be given credit for those new visitors — the new customers who made purchases, donors who made contributions, or people who at least signed up for a new account.

This is the job of affiliate and referral systems. Yet despite their importance, within the Drupal world they seem to be few in number and bereft of support. If you want to track users who provide fresh traffic, then you do not have many options from which to choose. Perhaps the best-known project in this space is the Ubercart Affiliate v2 module, covered in an earlier article. But what if you are not using Ubercart for the website in question? What if you are not interested in tracking the users who serve up paying customers or clicks, but instead you want to reward users who encourage new people to register for accounts? For these types of use cases, Ubercart Affiliate v2 is currently of no help.

One alternative — perhaps the only substantial one — is the User Referral module, contributed by Khalid Baheyeldin. It focuses on recording new registrations, and allows users to see a list of all the new users they referred, if any. The project page explains that when a (non-registered) visitor goes to a referral URL or the profile page of a referring user, then that visit is recorded in a browser cookie. Should the visitor register a new account when that cookie still exists, then the referring user (hereafter "referrer") will get credit for that new user (hereafter "registrant").

The best way to understand the capabilities of this module (as with any other), is to try it in a sandbox environment. As of this writing, the latest version of Drupal is 7.19, and the latest version of the module is 7.x-1.0-beta4; so those are what I will be using. Anyone reading this should be familiar with how to install Drupal core and contrib modules; hence I will go straight to setting the available options.

Configuration

After you have installed and enabled the User Referral module, you can either set permissions or referral options. I will start with the former. On the permissions page (admin/people/permissions), specify that authenticated users can refer other users, but cannot administer referrals or view the reports.

On the module's configuration page (admin/config/people/referral), I can set the referral link type to "User page" or "Referrals page" — although what those options mean is not clearly explained. The former option (the default) causes the referrer's unique link to be displayed on his profile page, but not visible to anonymous users. If the link type is changed to the latter option, then his referral link is displayed on the page listing his referrals (referral/view), described below.

Each referral tracking cookie will by default disappear after one day. This duration seems rather stingy, so you will need to increase it if you choose to encompass visitors who register more than 24 hours after first clicking on a referral link or landing on a referral profile page. My testing confirmed that once the cookie has been deleted (either manually or by the browser itself), then any new registrants are not credited to the most recent referrer.

After a visitor clicks a referral link, by default she will be sent to the path "user/register". This is the most logical choice, because it would be best if the visitor registers as soon as possible, especially before the cookie expires. But the path can be changed to any alternative, if needed for some reason.

There is another needed configuration setting, unmentioned in the module's documentation: On the account settings page (admin/config/people/accounts), in the "Registration and Cancellation" fieldset, the radio buttons "Who can register accounts?" must not be set to "Administrators only". Otherwise, when a prospective registrant visits any referral link, she will be forwarded not to user/register, but instead to user/login?destination=/user/register, where she will encounter an unpleasant "Access denied" message — not a good first impression of a recommended website. Either "Visitors" or "Visitors, but administrator approval is required" will work; I will initially choose the latter.

In the sandbox Drupal 7 website I will be using as an illustrative example, I must have at least one test referrer, in this case unimaginatively named "Test Referrer 1".

As an administrator, you might want to see the unique referral link generated for any user. Oddly enough, despite any superuser privileges, you will not see the referral link on any user's profile page except your own.

However, if you login as such a user, then you will see his referral link.

Each user, with the proper referral permissions, is given a single referral path — in this example, referral/6472757f — containing a unique hexadecimal value. (In the screenshots, http://drupal_7_test/ is the virtual host of our sandbox environment.)

Referrals from Links

The referrer can then publish that referral URL, and will receive credit for each new registrant who visits that URL and then opens an account within the cookie lifetime mentioned earlier. If a visitor goes to the path referral/6472757f, then she would be automatically forwarded to user/register, where she could sign up for a new account (here "Test Registrant 1"). If her account is pending approval by a site administrator, then the referrer will not yet receive credit, since unapproved and blocked registrants are not counted.

Both the referrer's profile page and the administrators' referral summary page (admin/reports/referral) confirm that the new account has yet to be counted.

When the new registrant's account is unblocked, then the referrer receives one credit. The administrators' referral summary page lists all of the referrers, the number of new registrants credited to them, and the datetime of the last one.

When the referrer views his profile page and clicks the "View users you have referred" link, he will see a "Your Referrals" page (referral/view) listing exactly that — in this example, the registrant's username, the referral's flag status, and the datetime when she registered the account using the referral link.

If the user account settings are changed so that requests for new accounts do not require administrator approval, and a new referred user signs up, then the referral is counted immediately.

The referrer too will see the new registrant.

Referrals from Profile Pages

A referrer can also receive credit for a registrant who does not use his referral URL, but instead visits his profile page. This of course necessitates that user profile pages be viewable by anonymous visitors. In our example, after enabling that permission, I can test a third visitor landing on the profile page at users/test-referrer-1.

If the visitor clicks on the link "Register to this site using my referral link" or the standard link "Create new account", the referrer will be immediately credited with that new registrant.

Note the "details" link on the right side of the table. As one might suspect, this leads to a page listing each individual registrant for the referrer, the datetime when she requested an account, and her IP address.

Flagging

If needed, referrals can be divided into two groups: flagged and unflagged. The default administrators' summary page (all those shown earlier) lists all referrals, flagged or otherwise. To see just the latter group, go to the "Unflagged Referrals" tab.

Note the "flag" link in the Operations column. This would suggest that clicking that link would flag all of the unflagged referrals for the given referrer. However, it only flags the oldest one in that referrer's group.

In our example, the most recent two referrals are still unflagged. (Incidentally, the text above the table appears to contain unparsed HTML.)

As expected, clicking the "flag" link (in the Operations column) a second time, again flags the (now) oldest one.

Arguably, it would be better if the "flag" link were located on the details page, one for each referral, thereby allowing more fine-grained control as to which referrals could be flagged. As it now stands, one can only flag the oldest referral, one at a time. Nonetheless, there are a number of scenarios in which this capability could be useful. For instance, if you want to establish a practice of reviewing each new referral, you could flag each one as you review it. In the future, you would not need to review the entire list, but only those referrals listed on the "Unflagged Referrals" tab. The same procedure could be utilized if you wanted to provide compensation to the referrer for each new registrant, and wanted to avoid accidentally giving credit for any referral more than once, or failing to give credit for a referral that might otherwise go unnoticed.

Other Topics

This module apparently can work with the User Points module. Also, the Drupal 7 port of this module, implemented by Matt Robison, integrated it with the Rules module, thereby extending what it can do through actions, conditions, and events. I will not cover these topics in this article.

Developers who wish to explore deeper, may be interested to know that most of the referral data is stored in a single table, appropriately named 'referral'.

In addition, there are three values stored in the 'variable' table.

Conclusion

The future of this module is uncertain. The most recent commits were made over a year ago. On the other hand, that may indicate that the module is quite stable. However, it appears that the unresolved — or at least unanswered — problems are piling up in the issue queue.

Regardless, if you need to track the referrals of new registrants on a Drupal website, then the User Referral module is probably your best choice.