Using AltaUserPoints/Alphauserpoints in jDownloads

 

NOTE

  1. In February 2016 a fork of AlphaUserPoints was created - the new name is AltaUserPoints. It is available at https://www.nordmograph.com/extensions/
  2. In May 2016  the original AlphaUserPoints and its web site was purchased by Pamper Me Network.. It is available at http://www.alphaplug.com/
  3. jDownloads supports both components.
AltaUserPoints is a fork of the AlphaUserPoints component originaly developped by Bernard Gilly at Alphaplug.com. It has been forked to save the project: continue distribution, support and software evolution when Bernard decided to retire. Adrien Roussel, Nordmograph
After almost ten years of development by French software developer Bernard Gilly, AlphaUserPoints, Joomla’s most powerful loyalty management software platform is now in new hands, with a recent purchase by the Pamper Me Network.  We will continue the amazing work of Bernard Gilly. However, there will be a fundamental shift in strategy. Going forward we will allocate significant resources to ensure that AlphaUserPoints supports mobile delivered apps, viral sharing of content, Word Press applications, Facebook applications and Twitter cards   Pamper Me Network http://www.fanrewardsnetwork.com

From jDownloads 3.2 v44 and higher both AltaUserPoints and  Alphauserpoints  systems are supported though the use of five jD specific 'rules'. In this  document we refer to AUP meaning either component. The AUP component must of course be installed.  The official AUP documentation often refers to these 'rules' as plugins which is very confusing as they are not plugins in the normal Joomla! sense.  However there is no cause for concern as the AUP has a function in its control panel to connect up these rules.

We recommend upgrading to AltaUserPoints.  Details of transferring are given in the section 'Transfering to AltaUserPoints'.

The objective here is to provide a guide on setting up AUP as far as interaction with jDownloads is concerned.  These notes are not a guide to using AUP in other situations.  However it is useful to briefly describe the use of AUP in a jDownloads context.  Basically each time a user downloads then their AUP 'account' is reduced by a certain number of points.  This may be a fixed number of points per download or it may be  the amount specified in the jD 'Price' field associated with that Download. Users may gain points by creating a new Download.  Also points may be given to the Download 'owner' each time a user downloads one of their Downloads.

If you are installing a User Points system for the first time then use the AltaUserPoints one.  If you already have Alphauserpoints installed then consider up grading to AltaUserPoints, see Transferring to AltaUserPoints below.  Note that you will not loose any information, points or similar as AltaUserPoints uses the same database. It is very simple to change over.

The first step is to install the AltaUserPoints component. Installation, and updating, is quite straight forward and is similar to installing  jDownloads. You can get the free AltaUserPointscomponent either direct from the Nordmograph site ( https://www.nordmograph.com/ ) or from the Joomla Extensions Directory (JED) http://extensions.joomla.org/extensions/extension/e-commerce/credits-a-point-systems/altauserpoints. Even though it is free the download takes you through a purchasing sequence with a zero cost, which seems a bit strange initially. The Zip file typically has a  name such as 'com_altauserpoints_UNZIPFIRST.zip' which needs  unzipping. After unzipping you will find a zip file such as 'com_altauserpoints-1.1php7.zip'. This  is the install file. The php7 in the name denotes  that it is php 7 compliant as well as  supporting earlier php versions, ffor example  the tests on AltaUserPoints were done on PHP 5.3.29. The last release of AlphaUserPoints was version 2.0.4 in December 2015.

After installing AUP and before using AUP there are a few things to set up in both jDownloads and in the AUP configuration.

 jDownloads setup for AUP

 In jD Configuration go to the Specials tab.  This has a section "Settings for AltaUserPoints/Alphauserpoints Support" which needs completing.

  1. Use AUP rules?  Set to Yes if you want to use in conjunction with jD.
  2. Use files price field for points?  This is where we select using either a fixed number of points per download or a variable number of points per download as specified in the jD Price field associated individually with every Download. For initial testing it is simplest to use No.  This means that every Download will be affected, which may be inconvenient.  For serious use of the system using Yes is probably better as you can then have 'free' downloads.  More on this topic later.

The AUP points dialogue is shown by the Summary Layout though the place holder {aup_points_info}. This  is typically in a line <div style="padding:5px;">{aup_points_info}</div> which is  included in the 'Standard Summary Layout v3.2'.  So always check that the active summary layout has a similar line of HTML code. For more information  on layouts see the documentation section http://www.jdownloads.net/documentations/category/editing-layouts.

The next jD item to set is to ensure that the Summary page will be shown.  That is set Configuration - Downloads tab setting Activate Direct Downloading to No.  For more information please see the article Download actions: Direct, via Summary Page or via Download Details

There is one more aspect of jDownloads that may need to be considered. This is the Download Duration in User Groups Settings. This setting allows a grace perod in which a user may make multiple dowloads of the same item without incurring additional 'charges'.  The objective of this parameter is to cover situations where a download may fail. But see also the note below about Download Managers.

However if you are initially testing it can cause an apparent failure to deduct points!  I certainly overlooked this when first checking out jDownloads and AUP.

AUP 35A

Getting Started:AUP aspects

After installing AUP go to the AUP Control Panel.  This has a large number of icons as illustrated below.   Only part of the AUP Control Page is shown below.

It will also have a message about Synchronising Users with AUP. But do not do this now.  Please first read the notes below.

AUP00

>

Perhaps the first thing to do with AUP is to use the Options Button which is located at the top  righthand side of the AUP Control Panel.

The picture opposite shows the default setting.

The first tab is of particular interest as it allows setting the format of the points, and more importantly whether accounts are allowed to go negative.  Setting the default format is sensilbe if you are equating points to a financial charge.  Allowing negative points is generally a poor idea as it can lead to a 'security' leak with users able to download multiple items at no cost.

AUP00D

AUP actions are controlled by a set of Rules which give it a wide variety of uses.

One such AUP rule is the ability to give new users some 'points' initially.  If you are going to give new users, that is your existing users when first installing AUP, some 'starter' points then that needs to be done before Synchronising Users.  Basically Synchronising users means adding in all existing users before AUP was installed.  After installation any new user will be added automatically.  In order to give new users an initial grant of starter points then it is necessary to edit the appropriate rule.

To do this click on the Rules Icon which will give a display such as the one opposite.

 

There are approximately 20 rules.  Later in this process five more jDownloads specific rules will be added

AUP00A
Scroll down, and possibly change to the next set, until you find the 'New User' Rule. AUP00B

Clicking on the rule brings up the relevant details such as shown opposite.  So if you are going to give all new users a starter number of points then edit the Points field as appropriate. Note this field has two decimal places like most "currencies". Then Save & Close.

On other tabs you can set up emails and messages.

After Saving & Closing ensure that the Rule is published.

AUP00C

If you have not previously used the AUP then it will not know about the regular Joomla! users you may already have 'registered' on your site.  Clicking on the AUP Users Icon at this stage shows that AUP does not know about existing users.

AUP 32B

The next step is to Synchronise the Users, that is adding all existing users into the AUP scheme.

To do this return to the AUP Control pane and click on the 'Synchronise Users icon.  A message saying 'Do not interrupt' may be displayed depending on how many users are already 'registered' on your site.  In due course it should give a successful completion statement. 

Clicking on the Users icon again will then show something like the view opposite.  Note in this case the 'New User' rule had not be set up so no one had any points!

Any new user added after AUP has been activated will added and granted an initial stock of points as set up in the New User rule.  There are a variety of ways  to give  users points.  One simple method is to add 'Bonus' points after setting some value in the Bonus rule.  You can also edit users accounts individually to add points.

AUP 32C
The next step is to add the jD specific Rules.  This is also very straight forward. Basically one just clicks on the 'Auto-detect new rules' button on the AUP Control Panel.  This should give you a message acknowledging that five more rules have been added.  There is no external plugin to be enabled as the relevant code is in the jD Component, but you will need to have enabled  use of AUP as noted earlier in  jDownloads setup for AUP.  alta install 03

The five jD specific Rules need to be setup.  So click on the Rules icon button and then select the 'Other' type in the pulldown near top right of the Rules page. Then search for the five jD rules in that section.  Click on the name part of the rule to access the details.

  1. User Upload published Assign points to a user when one of their uploads is published in jDownloads (may also be negative to reduce points).  Access Rule and set points value.
  2. User downloads a file  Assign points when a registered user downloads a file from jDownloads (may also be negative to reduce points). Access Rule and set how many points the Download will cost, typically a negative value.
  3. User downloads a file (uses price) Uses the value in the 'price' field in the Download. Reduces the points when a registered user downloads a file from jDownloads. Also see note below about Download Managers.
  4. Uploader get points for downloaded files Assign points to the file uploader when a user downloads this file from jDownloads. Uses a fixed number of points as defined in this rule. Access the rule to set the value.
  5. Uploader get points for downloaded files (use price) Assign points to the file uploader when a user downloads the file from jDownloads. Uses the 'price' field from the Download.
 AUP 31
Using Download Manager  
If you are using a download manager on your local machine then you might find that multiple 'charges' are being made against the user points.  This is because many 'download managers' open multiple 'streams'  Unless you set thing up in an appropriate manner then each 'stream' appears as if it were a fresh downloading of the original file. Hence there is a danger of multiple download charges!
 
The solution is to change the Method field of the User downloads a file (uses price) rule so that the user is only charged once/day for downloading that file, or another appropriate selection, such as illustrated opposite.  AltaPoints14A

 Note the 'charge once/day' attribute is applicable to each download individually as illustrated opposite.  Multiple downloads of the same Download will only be charged once that day.

If the user downloads multiple times in the selected period then these do not create an AUP event.

Other options include 'once per user' meaning that file is free for that user forever after.

Other options include once/week. once/month and once/year.

 AltaPoints14
   
jDownloads Layouts and Front End Views  

When AUP is active then jD will show the Summary Layout  This layout must contain the {aup_points_info} placeholder in order to show the user the information about the cost of download and how may points are in the users 'account'.

 AUP 34
If the user has insufficient points then a message such as shown opposite will appear.  AUP 38
If the user is not a member of AUP then a message such as that opposite appears.  AUP 37

Changing to AltaUserPoints

You can get the free AltaUserPointscomponent either direct from the Nordmograph site ( https://www.nordmograph.com/ ) or from the Joomla Extensions Directory (JED) http://extensions.joomla.org/extensions/extension/e-commerce/credits-a-point-systems/altauserpoints. Even though it is free the download takes you through a purchasing sequence with a zero cost, which seems a bit strange initially. The Zip file typically has a  name such as 'com_altauserpoints_UNZIPFIRST.zip' which needs  unzipping. After unzipping you will find a zip file such as 'com_altauserpoints-1.1php7.zip'. This  is the install file. The php7 in the name denotes  that it is php 7 compliant as well as  supporting earlier php versions, for example the tests on AltaUserPoints were done on PHP 5.3.29.

The actual change is really simple because:

  1. AltaUserPoints uses the same database tables as AlphaUserPoints;
  2. AlphaUserPoints does not  remove the database tables when it is  uninstalled.

The procedure is:

  1. Go to Joomla! Extensions - Manage, and the select Manage
  2. Search for Alpha, which will list the AlphaUserPoints Component and several plugins and modules.
  3. Select All and then Uninstall.  You should get messages for the component uninstall and for multiple plugin and module uninstalls.
  4. Go to Joomla! Extensions - Manage, and the select Install
  5. use normal sequence to install AltaUserPoints.

The only slightly odd thing is that AlphaUserPoints was version 2.0.x but AltaUserPoints is 1.1 at time of writing.

Colin Mercer July 2015, Revised May 2016, July 2016