Integrating the affiliate plugin part one
Tuesday, October 20th, 2009The 100th plugin recently released by WPMUdev was our wonderful affiliate system plugin. What better way to give back to your community for their support and word-of-mouth than to reward them with cold hard cash?
As a WPMUdev plugin it is configured to work hand in hand with our Supporter plugin, and so record user signups and supporter subscriptions, but it was built so that it could be easily integrated with just about anything.
In this post I will go through what the affiliate plugin does automatically and what you can change and customise. We’ll walk through the default supporter integration as an example.
Integration plugins
To keep things neat and tidy the affiliate plugin has its own plugins directory. You will find it within the main affiliatelite directory. It is called plugins so it should be easy to spot. The affiliate plugin searches this directory for plugins when it is initiated and ready.
When you first install the affiliate plugin you will find a single file in this directory. It is our default plugin called supporter.php. This is the one we shall be looking at today so, if you want to follow the code as we go through it then, open it up in your text editor.
Affiliate plugin built-in behaviour
The affiliate plugin is a simple beast at heart. Its default behaviour, when we strip out all of the graphing and reporting, is to simply sit and watch the first URL visited by a browser and determine if they arrived via someone we have an interest in recording (an affiliate). If they have indeed arrived from an affiliate, then it records this fact as a unique visit for the affiliates statistics, and sets a cookie on the visitors browser to mark that visitor as the “property” of the affiliate for the next 30 days.
Unless we are planning on paying per visit, we need to extend this behaviour to fit our business model.
The business model
In order to further integrate the affiliate plugin with your system you need to understand the most important revenue generating points of your business model. The supporter based business model is interested in two events. The creation of a blog, and the upgrade of a blog. We can identify the initial creation of a blog as a signup within the affiliate system, and the upgrade as a purchase or complete. With this in mind, let us look at the affiliate system’s supporter plugin and see how it works.
The supporter system integration
Looking at the supporter.php file we opened earlier you can see four add_action lines. For this tutorial we are interested in the first two actions as they provide the main part of our implementation.
Action one: wpmu_new_blog
When a new blog is created in WPMU, this action is fired by the WPMU system and passes along the identification number of the blog created and the user who created it. By adding this action, we have told the WPMU system that we are interested in receiving this notification and its associated information.
Scroll down now and look at the affiliate_new_blog function. It is only 2 lines of code and 2 IF statements, but they are very important ones.
The first line in the function is:
do_action( 'affiliate_signup' );
This is the most important line here, it informs the affiliate plugin that something has just happened that it should be interested in. In this case it is a blog signup. On receipt of this call, the affiliate plugin will trundle off and check if the person performing the current action is here because an affiliate sent them to us.
If they are, then the affiliate plugin will create a global define, called AFFILIATEID, which holds the user id number of the affiliate in question. By checking for the existence of this define we can determine if we want to record this blog creation as a signup for an affiliate or not.
Indeed the following line in our function does just that:
if(defined( 'AFFILIATEID' )) {
The next step is to mark this newly created blog with the affiliates identifier. This is so that we can identify the affiliate later on, should the new blog owner decide to upgrade to a supporter. As this may occur outside of the 30 day affiliate cookie lifetime, we can not rely on our cookie still existing.
The final lines mark the blog by creating an option against the blog with the affiliate users identifier in it.
if(function_exists('update_blog_option')) {
update_blog_option( $blog_id, 'affiliate_referrer', AFFILIATEID );
}
So there you have a simple piece of code that performs an important function. We can check for the existence of this option at any point during the life of the blog to see whether the affiliate in question is due some credit (money / time / etc).
Action two: supporter_payment_processed
The second action we are interested in is related to the upgrade of a blog to a supporter. Not many people will have seen or used this particular action because it is specific to the supporter plugin.
If you are integrating with a different system, then think of this action as the point when you have been notified that an order is complete or a payment has been received. This particular action is fired by the supporter system when it gets notification from PayPal that a payment has completed.
This second function, affiliate_supporter_paid, looks a bit more complicated than the first, but it really isn’t. In fact we can ignore large chunks of it as some lines only exist to allow the function to run on both WordPress and WPMU.
With that in mind, let’s skip down to the code in the second if statement (which merely checks to see if the get_blog_option function exists, so we can call it). The important bit is inside:
$aff = get_blog_option( $bid, 'affiliate_referrer', false ); $paid = get_blog_option( $bid, 'affiliate_paid', 'no' );
What does the above bit of code accomplish? It attempts to set two variables for later use. The first is aff, into which we attempt to grab the affiliate referrer identifier that we created in the signup function earlier. If that information exists in the system, then we grab it. If it doesn’t then we set our variable to false.
The second line checks to see if we have already paid our affiliate for this referral. On systems that handle recurring or subscription based payment models, a payment may be triggered more than once. In this particular scenario, we only want to pay our affiliate on the first payment we receive (the initial upgrade), so if a payment is already recorded then we need to know about it before we do anything.
Which is precisely what the following line does:
if($aff && $paid != 'yes') {
If we have a affiliate identifier and we haven’t already made a payment, then we want to do some processing and reward our affiliate. The next section of code is simply a switch statement which calculates the amount of money we are going to reward our affiliate based on the supporter subscription purchased. You will replace this code with whatever method you are using to determine an affiliates payment.
If we assume you are rewarding them with a flat amount then a line as simple as:
$amount = 10;
will set the reward at 10 (of whatever currency you are using, in our case USD).
Once we have the affiliates identifier and the amount we are going to credit them, we pass this information to the affiliate system for it to record. This is accomplished with yet another simple, but important, line:
do_action('affiliate_purchase', $aff, $amount);
That is the final step we need to integrate with the affiliate system. The last bit of code simply records the fact that the payment has been assigned, so that we don’t payout again (the define AFFILIATE_PAYONCE is set at the top of the affiliatelite.php file. You can set this to no or remove it if you want to make a recurring payment, or simply ignore it and mark the blog as paid if you don’t need the option).
Conclusion
That completes this part of the tutorial. We have walked through the two important actions of the affiliate system plugin and seen how to retrieve and record the affiliate and then make a later payment to them.
In the next part we will work on a new plugin that rewards the affiliate with an extra month of supporter subscription for each upgrade and will create a new affiliates settings form to handle the configuration.
