1. Use of UC Affiliate v2 - backdrop-contrib/uc_affiliate2 GitHub Wiki

UC Affiliate v2 allows sites that use Ubercart to provide affiliate functionality.

"Affiliate functionality" means that the site will pay commissions to "affiliate" users with the proper role when a visitor purchases something on the site through a special link the affiliate has provided. These links, by default, will look like: https://example.com/affiliate/[UID]/product/my-product.

Basic steps to create affiliates

  1. Create a role, for example, Affiliate
  2. Visit the site's permission page at admin/config/people/permissions and give that role "Act as an affiliate" permission
  3. Give that role to any user in the site

Setting the commission structure

By default, affiliates who are on the "top" of the affiliate line (see explanation below) will receive a 5% commission.

Commissions structures can be change for the whole site, for specific products (applied to a role or to a specific user), or for specific roles. Most of these settings can be changed at admin/store/settings/affiliate/commissions.

That page presents textboxes with percentages separated by commas. The first percentage is the one applied to affiliates who are at level 1 of the affiliate hierarchy. The second will be applied to the second level, etc. For example, if user D is visiting an affiliate link provided for user C, who is below user B in the hierarchy, and B is below user A, then user C will receive 5%, user B 3%, and user A 2%.

Setting the commission structure for a specific product

  1. Create a product
  2. Visit node/[NID]/edit/commissions for that product
  3. Set the structure for this product for:
  • All affiliates
  • User role
  • User
  1. It's possible to set several conditions in this page. The top one to match will be used. You may want to put the more general "All affiliates" at the bottom.

Setting up the affiliate functionality

The settings at admin/store/settings/affiliate/settings are very important for the correct functioning of the affiliate processing. Especially important is the "Order status" setting. Notice that if this is set for "Completed" orders, commissions will not be applied until the order status changes to "Completed".

You may choose two statuses, for example "Payment received" and "Completed. But once the commission has been applied when the order has changed to "Payment received", it will NOT be reapplied if the status changes to "Completed."

Also notice that if an order status changes to one that doesn't receive commission, any commissions previously applied for that order will be removed.

About cookie tracking

In the Settings page for Affiliate admin/store/settings/affiliate/settings you will see the option for "cookie tracking".

By default, when cookie tracking is not enabled, UC Affiliate v2 tracks activity by setting a SESSION cookie, and keeps information about the affiliate referrer by saving it the session table of Backdrop. This allows for tracking future purchases, even if the visitor doesn't reuse the affiliate link. But the SESSION is only stored for 24 hours.

A more persistent way of tracking purchases is to enable cookie tracking. This sets a special, long-lasting cookie in the browser itself, meaning that if someone else uses that browser, any subsequent purchases will generate commissions for the affiliate who first referred the visitor to the site.

Affiliate store path

UC Affiliate v2 provides the default path affiliate/[UID], where UID is the user ID of the affiliate user. Visiting this path (as in https://example.com/affiliate/[UID]) will start a new session (or set a cookie) if one didn't exist for the browser, and will link that session to the affiliate with user ID UID. You can add anything to that path, for example https://example.com/affiliate/[UID]/node/2 will create the session, and then redirect the visitor to the content with node ID 2.

This path will work "out of the box" - no need for any special setting.

Every time a new visitor (one who doesn't already have a session or a cookie in their browser) visit the store by using the affiliate path, that visitor will generate a "unique click" for the affiliate. Those can be checked in the affiliate dashboard in the "Affiliate Center" page at user/[UID]/affiliate.

Notice that if a session (or a cookie) already existed in the visitor's browser (because of a previous visit), a new session will NOT be created, even if the visitor uses the path for a different affiliate. If using cookies, that will mean that that particular browser will remain "linked" to the affiliate for a full year, and all future purchases on that site will apply a commission to that affiliate - unless the visitor deletes the cookies for the site in their browser .

Also notice that, if a visitor tries to use a path for an inexistent affiliate UID, they will get the error: You are attempting to access an affiliate store that does not exist. Please check the address and try again.

There are additional settings for the path at admin/store/settings/affiliate/settings. For example, you may choose to use a query string instead of a full path, as in https://example.com/node/1?a=[UID].

Generating affiliate links

UC Affiliate v2 can also generate personalized links for affiliate users. You (or the site affiliates) can get those by going to user/[UID]/affiliate/links. That page can generate HTML code that can be copied and pasted into other sites, and can also download a CSV table with those links. The links generated this way will point to specific products in your Ubercart store.

The format of these links can be customized by going to admin/store/settings/affiliate/banners and changing the HTML template there.

Affiliate store dashboard

Affiliates have access to a dashboard that lists lots of information, at user/6/affiliate/.

  • Commissions (notice that for privacy, the user ID or username of the customers are not accessible to the affiliates)
  • Unique click counts
  • List of orders linked to the affiliate. That listing includes orders that may not have yet generated commissions (for example, if commissions are only applied when the order status changes to "Completed").
  • "Downline" affiliates

Paying commissions

The site administrator has access to reports for all affiliates at admin/store/settings/affiliate/reports. There, if you click on the amount, you can change the "amount paid" after you transfer the commissions to the affiliates.

At this point, these paid commissions can only be updated manually, one affiliate at a time. It is possible, however, to create a Bulk Operation that will do this automatically in a View.