Composr Tutorial: Creating an economy/reward-system for members via points

A logged-in member may see their points from the header

(Click to enlarge)

Members with the “Use points” privilege can earn points through various actions on the website. The points system introduces a community dynamic that encourages member participation – or even competition – where website members can increase in rank and spend their accumulated points. Points facilitate a micro-economy, with points being equivalent to money. Members can spend those points on site products, services, or account upgrades… or they can send or escrow them to other members for appreciation or payment for goods and services.

Earning points

Configuring the points balance

(Click to enlarge)

The points tab on a member's profile (Conversr)

(Click to enlarge)

There are many ways to earn points in Composr. You may not wish to educate your members on the precise details of these, although of course they could educate themselves by reading this tutorial.

Methods of earning points include:

• Joining
• Visiting the site
  • Bonus points depending on browser / platform criteria (see “A note about daily visit points”)
• A daily stipend ('Universal Basic Income')
• Voting in a poll
• Rating content
• Having your content being liked
• Poll being chosen
• Submitting various forms of content (See “A note about points and content validation”)
• Posting on the forum (see “A note about forum points”)
• Posting in a chatroom
• Entering/passing quizzes
• Recommended the website to others
• Receiving points from other members (this is described in a later section)
• Earning points from selling a download (this is described in a later section)
• Birthdays (see “A note about birthday points”)

Most methods of earning points may be altered in the configuration (Admin Zone > Setup > Configuration > Points options), so that the number of points earned from various activities is appropriate for your website.

There is a distinction between the point count for points available for spending (points balance), and the point count for the total points ever earned (which contributes to rank and leader-board position) (life-time points). This will usually be made explicit, but sometimes context will let users easily identify what is the appropriate meaning.

A note about daily visit points

There exists an additional section of options which allows you to credit bonus daily visit points depending on the browser / platform a member uses (see Admin Zone > Setup > Configuration > Points options > Browser / Platform Points). An example use could be rewarding members who use Open Source browsers or operating systems. The following options are available:

• Browser / Platform points per daily visit: Set this to the number of daily visit points a member will receive (in addition to Points per daily-visit) if their browser / platform matches all the criteria specified. Set to 0 to disable this feature.
• DNT (Do Not Track) / GPC (Global Privacy Control) HTTP Header: A "Do Not Track" / "Global Privacy Control" header can be sent in the browser to tell websites that the user wishes not to have tracking data collected about them. If ticked (checked), members must be sending either the DNT or GPC header to receive the bonus points.
  • The DNT header has been deprecated from web standards, however it is still supported by most major browsers.
  • The GPC header is a new standard that is not yet widely supported in browsers.
• Inclusive User-Agent Regular Expression: You can specify a Regular Expression that must pass when tested against a member's browser and/or platform for them to receive the bonus points. For example, specifying /(Firefox|Brave|DuckDuckGo|Linux)/ means the member must be using a Firefox, Brave, or DuckDuckGo based browser, or running a Linux operating system, to receive the bonus points.
• Exclusive User-Agent Regular Expression: You can specify a Regular Expression that must fail when tested against a member's browser and/or platform for them to receive the bonus points. For example, specifying /(Chrome|Edge)/ means the member will not receive bonus points if they are using the Chrome or Edge browser. Use this option with caution; some web browsers might include other web browsers in the User Agent if they are based off of them, although Chromium-based browsers running on HTTPS websites will be checked via the Sec-CH-UA headers which generally is accurate.
  • We gave the example of Chrome because Chrome is close to a monopoly taking a large majority of the browser market share. You might want to try and encourage browser-engine competition to avoid promoting a "browser monoculture".
  • We gave the example of Edge because Microsoft uploads telemetry data and syncs browsing data to their servers by default.

Note that all specified conditions must be satisfied for a member to receive the bonus points.

A note about points and content validation

The earning of points for submitted content can be considered encouragement for participation more than as a judgement on the particular quality for that content. Therefore points are credited as soon as content is submitted, regardless of validation. Points can always be reversed by ticking (checking) the “Reverse point transaction” box when editing/deleting content.

Forum posts are treated differently to other content, due to the prevalent problem of spam. Spam is not just low quality content (which is common and allowed on most forums), it is intentional abuse of the website. Therefore, when a submitted forum post requires validation, points will not be credited until the post is validated. If you want to encourage high quality content with points, the awards addon can be utilised to award high-quality content and subsequently credit the awardee some points.

A note about forum points

For Conversr, points are awarded when a post is made, and points can be reversed via a tickbox (checkbox) when deleting posts or topics. Note that points are not awarded for anonymous posts, whispers, nor posts in private topics because it would cause a privacy leak in the points ledger (not to mention these are considered private methods which do not make any significant contribution to overall site content).

For all other forums, because the forum driver cannot directly communicate with Composr, points are instead awarded daily via the system scheduler based on the change in post count. Note that points will never be debited if the post count goes down; moderators should manually charge members to resolve discrepancies.

A note about birthday points

If birthday points is set to greater than 0, then members and staff cannot edit their own birthdays once they set it. This is to prevent birthday point abuse. Members should contact a staff member if they made a mistake in their birthday. Staff members would have to contact a different staff member as they cannot edit their own birthdays.

Sending points

Gift points (advanced)

By default, members have a single point balance that they can use both to spend on things and to send to other members (if they have the “Send points to other members” privilege). However, website administrators can enable a separate gift points balance by ticking (checking) the “Enable gift points” configuration option (under Admin Zone > Setup > Configuration > Points options > Gift points).

Gift points (when enabled) are a separate point balance allowing members to send points without affecting their regular points balance. Gift points cannot be spent on anything; they can only be sent to others as a gift. They also cannot be used in escrow because that would by definition constitute spending in exchange for a product or service. Gift points become regular spendable points for recipients when they are sent. Members receive a configurable amount of gift points per day that they can send to others based on which usergroups they are in. When a member tries to send more points than they have in gift points, the remainder will be deducted from their regular points balance. Confirmation screens ensure the member understands how their points will be distributed.

For example, member A has 100 points and 25 gift points. They can spend their 100 points on things, but they cannot spend their 25 gift points. Member A wants to give Member B 50 points. Since member A only has 25 gift points, the other 25 points will be deducted from their regular points. Therefore, after the transaction, member A will have 75 regular points and 0 gift points. And member B will receive 50 regular points which they can spend.

When gift points are enabled, members can be randomly rewarded spendable points for sending points to others. The amount rewarded and the chance of being rewarded can be configured (Admin Zone > Setup > Configuration > Points options > Gift points). Only non-anonymous transactions (if anonymous transactions are enabled) will qualify for this random lottery.

Points escrow

Members can also send each other points through the escrow system. This is commonly used when exchanging points with a written agreement, such as for a product or service.

To escrow points to another member, go to their points profile and click the “Send via Escrow” button. A form loads where you can specify the number of points to escrow, the reason (short and concise explanation of what is being exchanged with the points, such as the product or service), the expiration (deadline) if applicable, and the written agreement associated with the escrow. Only those with the “Escrow points to others” privilege can escrow points to others, which is enabled by default for all usergroups.

Once an escrow is created, the points will be deducted from the escrower's points balance and held in the system. Note that gift points are not used for escrows because that is not allowed (gift points are not used for spending, and escrows are considered spending). The other member will be notified that an escrow was created along with the written agreement. Once the agreement has been satisfied, both members must mark the escrow agreement as satisfied on the escrow screen. When that happens, the recipient member receives the escrowed points.

If an issue arises with the escrow, either member can dispute the escrow and provide a message explaining the dispute. When an escrow is disputed, those with the “Moderate points escrowed” privilege will be notified, and one of them can take an action. The action could be cancelling the escrow / returning the points back to the original member, marking the escrow as satisfied and giving all the points to the escrowed member, only crediting a partial amount of points to the recipient and returning the rest to the sender, or amending the text / agreement on the escrow. An escrow will also automatically be disputed by the system if only one member marked it as satisfied and the escrow expires.

Be aware that those with the “Moderate points escrowed” privilege cannot moderate escrows in which they are the sender or recipient; someone else with the privilege must resolve any disputes with that escrow.

If an escrow expires and neither member marked it as satisfied nor disputed, then the escrow is cancelled and the points returned to the original member.

Escrows can be viewed in a table on each member's points profile. Only those with the “Moderate points escrowed” privilege can see all escrows. Otherwise, members can only see escrows in which they were either the sender or recipient.

Point transaction notifications

There exists two types of notifications for point transactions: “Your points transactions” (available to all members) and “Others' points transactions” (available to staff). Notifications are generally only dispatched for the mentioned types when these conditions hold true:

• Transactions happening which the recipient would not otherwise reasonably know happened. For example:
  • transactions from other members
  • transactions sent by the system scheduler
  • transactions that are highly-tangential to an action the recipient is doing, yet are of significance (for example, getting points for a content submission)
• When other notifications are not going to be sent to you at the same time (for example, the “Your content was liked” notification would mention credited points, and no other notifications would be sent)

Transactions might not be delivered as a notification at all if they are insignificant (e.g. chat message points) or the member would reasonably know they would earn points (e.g. daily points). Members can regularly check their points profile to monitor their points.

Viewing the points ledger

The full points ledger is accessible in the Admin Zone > Audit > Points ledger. There, you can see all of the points transactions that occurred on the website. Additionally, members can view their own ledgers on their points profile. And if they have the “View others' point ledger” privilege, they can view the ledgers of other members on their points profile. Be aware that anonymous transactions (if enabled) will not show for members not involved in them (unless the member has the “Trace the origin of anonymous point transactions” privilege). Therefore, the total tally of a member's points received or sent may be higher than what the visible ledger sums to on a member's profile, but it will never be lower.

Modifying points

Those with the “Moderate members' points” privilege will see a “Modify points” box on member points profiles instead of “Send points”. This allows them to indirectly modify the points of others. A drop-down will be provided which allows, in addition to the sending of points, these actions:

• Credit: Credit (add) points to a member from the system. An example is to refund them for an outside purchase, or to reward them for something on behalf of the website.
• Debit: Debit (remove) points from a member to the system. An example is when a member makes a purchase outside of eCommerce and points escrow, or when they are being punished outside of a warning.

Crediting or debiting points, just like sending points, will create a new transaction visible in the ledger. It will also send a notification to the member (if they have the “Your points transactions” notification enabled).

Modifying point transactions

There are two permissible edit actions for point transactions: reversing a transaction, and amending the reason text.

When you reverse a transaction, that involves creating a new transaction that offsets the original one. For example, Bob sends Sue 50 points in the form of 25 gift points and 25 regular points. When reversing this, a new transaction will be created where Sue sends back 50 regular points to Bob, and Bob receives them as 25 gift points and 25 regular points. The two transactions will also be linked together so the ledger displays that one reversed the other. Escrow cancellations and undoing warning charges work in the same way. To reverse a transaction, those with the “Moderate members' points” privilege can click the “Undo” icon in the actions column next to a point transaction either in the ledger or on a member's points profile. If you reverse a points transaction created from an escrow, the escrow will also automatically be cancelled.

The “reason” text for the ledger is the only thing that can be amended in a transaction. Those with the “Amend reason on point transactions” privilege can either use the Points ledger (Admin Zone > Audit > Points ledger) or the transactions on a member's points profile to amend the reason text.

A note about points refunds (advanced)

There exists an API method to refund any amount of points (such as a partial refund). This is a low-level method and, to avoid competition/confusion with transaction reversal, is not available for direct UI use. The method is indirectly used in two places: points escrow moderation (when completing an escrow but specifying only a partial amount to be credited to the recipient; the rest are refunded back to the sender) and points transaction reversal (as the mechanism for refunding the points).

Other economy tie-ins

Voting power in Topic Polls

Site administrators can enable the ability to weigh poll votes on Conversr Topic Polls based on the number of life-time points a voter had at the time of voting. This means members with more life-time points have a greater effect / voting power on a poll's results when they vote.

This is covered more in-depth on the Forums page.

Buildr (non-bundled)

Buildr is a very large addon for Composr, made by the developers in a semi-official capacity. It is not included with the main release as it is totally inappropriate for non-community sites, and hence would be consider as 'bloat' (an excessive feature that gets in the way and causes undue complexity and confusion) by most.

Buildr is essentially a game, where members may move in, interact with, and create, a limitless world of rooms, split across multiple themed 'realms'. It can be used to create puzzles, adventures, board games, simulations, and with imagination, many other things.

Points are at the very core of Buildr, and are used in two ways:

1. It costs points (according to a configurable price) to add content to Buildr. Of course, members may try and redeem these points by asking members to send points back to them, but this feature prevents abuse and limits the need for moderation.
2. Members may add items to the system, and then sell these items to other members. An example of this being used, is for the controller of a realm used for a 'quest' to add a 'healthy' item into the system: those with more points have a higher chance of surviving to the end of the quest, as they can heal themselves.

The Buildr system is very simple, yet via the small set of options available, presents amazing possibilities.

Downloads

Members may submit downloads that cost points to download. Depending on how the submitter configures the download, these points may end up with that submitter, or thrown away.
This system allows:

• staff to artificially limit access to ensure members participate before they can use site resources.
• members to earn points to compensate themselves for the work contained within a download.

This is covered in the Advanced provision of downloads tutorial.

The real world

A small number of sites may wish to set up a system to allow members to exchange points for real money, or tangible products or services. Sites that may wish to do this are likely to be sites where the earning of points has a real effect on business goals, such that real-world reimbursement may be appropriate; for example, on a site where members collaborate on art for a published catalogue.

Alternatively, and perhaps more popularly, sites may allow members to exchange real money, for points. Hence web-masters could earn money from their more enthusiastic members, and those members could elevate themselves on the website.

The eCommerce addon allows setting up custom products that may be purchased in either real currency or in points. It is flexible enough to allow the above scenarios, although it would require either doing the conversions (e.g. crediting a member with more points after they buy some) by hand, or some custom coding.

Rank in Conversr

Gift Points and Groups (advanced)

When gift points are enabled, the number of base gift points and gift points earned per day can be configured per usergroup. This allows setting groups or ranks which earn progressively more gift points as members rank up.

Be aware that unlike regular points, the gift points balance is dynamically calculated. This means if a member transitions to a group with more or less gift points, their gift points balance will be adjusted immediately and retroactively. It is highly recommended that as a member ranks up, their gift points increase. Remember that members will take the best setting of all groups they are in, including gift points.

For example, Bob has been a member for 10 days. He is in the "Newbie" usergroup which awards 25 base gift points and 1 gift point per day. So far, Bob used 10 of his gift points. Bob will have 25 gift points in his balance (25 base + [10 * 1 daily] - 10 used). But Bob gets promoted to "Regular", which has 30 base gift points and 3 gift points per day. Bob's gift points balance will immediately change to 50 gift points (30 base + [10 * 3 daily] - 10 used) as a result of the promotion.

The leader-board

Tenets of the point system

The point system is designed to provide high levels of transparency, as a legitimate micro-economy. These strict tenets apply even for the highest privileged members.

Public ledger

Assuming members have the “View others' point ledger” privilege (which they do by default), the ledger is publicly available. Members can view each other's ledger on the points profile. And those with access to the Admin Zone can view the combined ledger at Admin Zone > Audit > Points ledger. When a member does not have this privilege, they can only see point tallies for life-time points, points balance, gift points balance, points sent, and points spent on members' profiles.

An exception:
Senders are not visible for anonymous transactions (if enabled) unless members have the “Trace the origin of anonymous point transactions” privilege.

In order to help assure users on the long-term integrity of the ledger, there is an option to download a spreadsheet (on any member's points profile), and also an RSS/Atom feed of transactions. These allow members to collectively download records and compare them at a later date.

Immutable ledger

The ledger serves as a transparent and honest record of every point transaction that took place on the website. And members should be able to trace every transaction that took place.

It is not possible to edit transactions, with the exception of the reason text. We carve out this exception because it is important to be able to moderate potentially dangerous or illegal content from any part of a website.

It is not possible to delete transactions; reversals and refunds always result in a new, linked transaction being created to offset the original one.

Even the system maintains the immutability of the ledger.

Of course, a webmaster could always edit the database by hand, but we would discourage this because, unless done under exceptional circumstances, it is a violation of trust.

Transactions cannot involve negative points

The system does not allow negative points in transactions of any kind. Instead clear positive transactions must be added to the ledger.

Negative balances

Members can have a negative balance. Various things could put a member into this state (such as a manual debit or charge of more from a member than they have). Nothing the member can directly do themselves can lead to them having a negative balance, however.

The only time a member can have a negative gift points balance is if they get demoted in their usergroups, and the resulting change in base gift points / daily gift points puts them in the negative due to the gift points they already used. Members cannot use more gift points when they have 0 or a negative number in their balance; instead, regular points are tapped when sending points to other members.

Points system implementation details (advanced)

Points are calculated from the ledger but there is some caching

The ledger serves as the real source of truth for calculating how many points a member has. While the number of points a member has in their balance and the number of life-time points a member received is tallied in a custom field, these fields cannot be edited on the UI and only serve as a non-volatile cache.

Syncing issues with Points balance and Life-time points

It is conceivable for a member's life-time points and/or points balance to get out of sync with the ledger. This would only happen due to a bug or to manipulating the ledger outside of the Composr API (e.g. the database). Should this happen, you can trigger a re-calculation of these values (custom fields) in the Admin Zone > Tools > Cleanup tools and tick (check) “Points Cache”. Re-calculation is a resource-intensive process and therefore only done when triggered through the Cleanup tools. Otherwise, the custom field values are adjusted when point transactions are made.

Gift Points are calculated dynamically

The number of gift points a member has is calculated dynamically (if gift points are enabled). First, we take the highest base gift points setting from all the usergroups the member is in. Then, we take the highest gift points per day and multiply it by the number of days the member has been a member, adding it to the base gift points. Finally, the number of gift points used (according to the ledger) is subtracted from this maximum to get the final gift points balance.

This means a member's gift points balance can change when their usergroups change.

See also

• Running advertisements (via the banner system)
• Providing downloads
• eCommerce
• Discussion forums

Feedback

Have a suggestion? Report an issue on the tracker.