# UserPoints - 4.x - Help

Presentation: UserPoints is a Referral User Points System. It's is a component that can distribute or assign points to registered users according to some of its actions and activity on your website. UserPoints acts as an incentive promoting participation of users. Users often strive for more recognition, as well as competition. It's also usefull for contest, challenge, participation, game, online store. This component has its own component of invite/recommendation for refer which can also be used by non-registered users (based on AlphaRecommend).

License: UserPoints is made under license GNU/GPL License.
Installation: Installing the component via the administration interface Joomla. During installation, plugins systems and module administrator are installed and are automatically published. If, however Plugins directory does not have permission in writing, an error and warned the user. The component will be reinstalled after amendment rights in the directory Plugins.

Migrate from AlphaUserPoints or AltaUserPoints Database tables are the same for all three extensions. So you can easily migrate. To migrate your 3rd party extensions rules and plugins, only remove alpha/alta to leave userpoints (case sensitive) in your codes.

General Control panel of Joomla:

During the installation of UserPoints, an icon is added to the general control panel of joomla (mod_aupadmin). This icon allows you to quickly launch UserPoints and display also a warning if there are pending approvals.
UserPoints Control panel:
Button / menu Rules
This menu provides access to the list of rules to award points according to some actions of the registered user. The descriptions of the rules will give you information on their roles and conditions for awarding points. To install new rules inter-acting with third components, see To go further.
Button / menu Users
This menu displays all registered members of the site with their respective IDs AlphaUserPoint, total points for each current members and a link to the details of every action having reported points.

Button / menu Activity
This menu displays all activities of members of the site with possibility to export in CSV format.

Button / menu Templates Invite
This menu displays list of template for invitation by e-mail and allows create it. 3 vars available to put in the body of the e-mail: {name} to show the name of the sender and {custom} to show the custom text writen by the sender. Var {link} display the link created to invite in the body of the message.
Button / menu Sync. users
This menu allows, after the first installation, synchronize Together members already registered on the site to their assigned an AlphaUSerPoints identifier (referral id). Before synchronize users, please read the Getting Started section.
Button / menu Recalculate
This menu allows you to launch a recalculation of the total number of points for each member after removal or modification of action points by an administrator.
Button / menu Reset all points
This menu reset all the counters to zero points for all registered members. You can set this counter manualy for each member (menu Users Statistics)
Button / menu Set max points
This menu sets a maximum limit of points can be assigned to all registered members of the site. 0 or blank if you do not set limits. You can set max points manualy for each member (menu Users Statistics).
Button / menu Purge expires points
This menu allows purging all user points with a deadline of validity. Important: This action results in an immediate recalculation (auto) of all points and for all users.

Button / menu Categories
This menu allows to create some categories for raffles, coupon codes and ranks/medals.

Button / menu Coupon Codes
This menu allows to create Coupon Codes for extra points for your users. Code generator and coupons generator.

Button / menu Raffle
This menu allows to create raffle, lottery or promotions for your users. 1 to 3 winners for each raffle.

Button / menu Rank s/Medals
This menu allows to create ranks and medals for your users. Both can be combined.

Button / menu Statistics
This menu display Top 10 winning points and Top 10 Points spent by users. Filter by date.
Button / menu Export active users (CSV)
This menu launches export in CSV file first fifty of the most active members (with the most points).
Button / Menu Export e-mails (CSV)
This menu launches export in CSV file of all email addresses stored in the table details of the component following an action-type invitation/recommendation, recommend an article ...

Button / Menu Combine Activities
This menu allows to combine the set of all actions in one activity from a specified date (perform database if you have huge activity).

Button / menu Report system
Use this menu to helps moderators and community on the support forum better understand your setup when you're troubleshooting. Paste the contents of this field in your post when requesting help on the support forum.

Button / menu Auto-detect new rules
This menu allows you to add new Plugins/Rules inter-acting with third components. After intsall a new extension for Joomla!, when this extension has rules and interactions shares UserPoints, then just click the button and the new rules will be added automatically. For more information on this menu, see To go further.
Button / menu About
Information on the component.
Button / menu How to create a plugin
This menu displays a help file explaining how to integrate the API UserPoints in a third component and how to generate an XML file installation of the new rule concerning this third component.

Button / menu Rules list
Display list of official extend rules for UserPoints.
Button / menu Help
Displays this file.
Getting Started:
Setting pre-existing rules
Via the administration interface Joomla! Click on the menu components then on the menu UserPoints. Then click on the submenu rules or click the rules if you are already in the control panel of UserPoints component .
When you launch the device for the first time, an informational message appears in the control panel component. This message informs you that you must first synchronize users / members registered with UserPoints. However, if you want to award points to each registering a new user, and not to penalize the former members, you must set the rule for new members before making synchronization. Edit this rule and assign a number of points for each new member. Save this rule. You are now able to synchronize all members. These will be credited with points. As soon as a new member will, it will be credited with the number of points specified in the rule.
Set and enabled other rules according to your needs. The descriptions of the rules will give you information on their roles and conditions for awarding points.
Note: The rule for new users can not be disabled. You can only save to zero the number of points awarded for this rule if you do not wish to assign point on this action.

1. Rule New user: Assigned or not points for each new user registered on the site.
2. Rule Invite: Assigned or not points when a user to ask someone else to register on the site (send email).
3. Rule Invite with success: Assigned or not points to the refferal user when a user registers on the site following an invitation.
4. Rule Reader to author: Assigns points to the author when one of its articles were read by a user.
5. Rule Referral points: Referral users earn bonus points as a percentage on all points earned by their referrees.
6. Rule Bonus points: Assigns bonus points to specific users (Backend -> UserPoints -> menu Users statistics).
7. Rule Change user level (1) : Specifies a number of points sufficient to authorize a registered user to change level. *
8. Rule Change user level (2): Specifies a number of points sufficient to authorize an author user to change level. *
9. Rule Change user level (3): Specifies a number of points sufficient to authorize an editor user to change level. *
10. Rule Winner notification: Sending a message to the user and administrator, when it reached the maximum number of points required (requires setting max points).
11. Rule Coupon points codes: Allows users to enter a code in the module appropriate to get extra points. You must install the module mod_userpoints_couponcode.
12. Rule Raffle: This rule allows to enable a raffle system.
13. Rule Custom: Assigns or remove custom points to a specific user and set a reason (Backend -> menu Users -> Details -> Toolbar -> Button Custom points)
14. Rule Profile View : Assigns points to the owner of the profile when the current user looks at a profile
15. Rule Combined activities: Allows administrator to combine the set of all actions in one activity from a specified date (perform database if you have huge activity). This rule is necessary to show the combined activity on the activities of users.

There are also 4 auto-detect rules if Kunena forum is installed on the website. This 4 rules allows to assigns points on post a new topic, reply on topic, ThankYou and delete post.

* Important: To use change levels rules, users must have only one group. Not possible to works with few groups: e.g. registered and super-user. And each level must be in the same tree and follow a progressive ranking : e.g. a registered member can be use the "Change level 1" rule to become an author, "Change level 2 " rule to become an Editor, "Change level 3 " rule to become a publisher. Not possible to change on another tree. Iif the points back below the threshold current level , the user returns to the parent level of this current level.

Creating menus
UserPoints includes 7 options for creating menu on frontend.

- A menu to display the profil/account of user connected with the total number of points, medals and statistics. This menu will be mainly used to match the user menu.
- A menu to display the list of all members with total points and referre ID.
- A menu to start the invitation / recommendation. This invite can also be used by guests (non-members, no points). This menu has several specific parameters for security (anti-flood) and the import of email addresses (integration with OpenInviter). IMPORTANT: Using OpenInviter option require com_openinviter installed first.
- A menu to list medals awarded
- A menu to display a link to RSS feed of latest activity
- A menu to display the latest activity with pagination
- A menu to display the list of the available rules to earn or spent points

To use ReCaptcha (anti-spam), you must first obtain keys for use on the site http://www.google.com/recaptcha.
To create a menu selected UserPoints component in the interface for creating menus Joomla! then choose the type of menu to create. Enter a name for this menu, then set it if necessary. For more information on creating menu under Joomla! See you using Joomla!.

Allows guest user to see profile members
Use the menu Configuration and enabled or disabled to allows guest user to see profile members.

Change the prefix identifier
You can change the prefix identifier UserPoints in Configuration menu. You can enter a particular prefix for users to register themselves on your site and another for users by referrer. 7 characters maximum.

Modify Referral ID type:
You can change the type of identifier UserPoints in Configuration menu. Choose between randomize or Username as the referral Identifier.

Limit daily points:
If you want to limit user points earned by day, you can enter a number in Configuration menu, otherwise leave empty.

Integration:
If you want to use Uddeim message or JomSocial notification instead e-mailing UserPoints notification, enabled in integration tab in configuration (button Options) and select an admin ID from the list. Thinks to enabled notification and set the message for each rule in the rules manager.

Raffle system:
First step: If you want offer a raffle to you users, you must enabled the rule "Raffle". Then, add a raffle and settings it. You can choose to offer points, coupon code to your registered users or an e-mail with a link to download something.
Second step (optional): If you have choose a registration for a raffle, you can put in a content article this following tag to activate the Joomla content plugin: {AUP::RAFFLE=ID} where ID is the ID of your raffle. This tag display a button to raffle registration to your registered users. If multiple entries is allowed, then a user can subscribe more than once to a raffle (as a system tickets/billets lottery).
To show a link to invite friends to register to a draw (if this raffle is with multiple registrations of course): type {AUP::RAFFLEINVITE=ID} where ID is the ID of your raffle. If this tag is in an article, it can be used by any registered user and the referral user get a free additional subscription (one free additional ticket/billet) when the new user made the first registration to the raffle. If this link is sent by a registered user to a friend not already registered on the website, then invite and invite with success rule works primary and the referral user earn one free additional ticket/billet after first registration to the raffle too.
To show the list of tickets/billets subcription for the current user logged-in: type {AUP::RAFFLETICKETS=ID} where ID is the ID of your raffle.
NOTE: button show on frontend only to registered users if registration is Yes, and then registered users can join to raffle. If registration is No, then all users are automatically in raffle (only once).
Samples :
If registration enabled - users (not guests) must make registration in (subscribe to the) current raffle to participate in it.
If multiple registration - users (not guests) can take more chances to win with additional registration (as additional billet in lottery)
If public - everyone who registered on your site (not guests) will participate automatically (with 1 billet).

Now, in backend, you have the number of enrolled users in this raffle. If you click on this number, You can show and export the entire list of participating in this raffle in csv format.

Level/Rank and Medals :
Both can be used together or individually. Ranks or medals can be awarded automatically when a user reaches a certain number of points (enter a number of points in the rank/medal) or can be assigned manually to a user (Set to zero point). In all cases, the rank or medal can be modified manually by administrator directly in the detail user. If you assign a rank that is normally intended to be assigned automatically to a certain level of points, it will not be taken into account. It is recommended not to mix the two types of rank (automatic or manual).

When you assign a medal to a user, you can add a description or a reason for award. If you leave blank, the default description of the medal is assigned. The default ranks and medals created during installation of the component can be removed without problem if you do not use them. If there is no rank/medal, the columns to display the icons or the number of medals will not be displayed in users management.

Check version :
You can show/hide the checking version in Configuration menu.
To go further:
Installing third plugins
Detect new rules : To detect new rules or from inter-acting with third components, click on the button of control panel component named "auto-detect new rules" after each new install component or plugin.