UserCredits

Introduction to UserCredits

IMPORTANT: The UserCredits underwent a major rewrite for version 4.0. If you're upgrading from V3.x to V4.x, you MUST make the changes set out on the Upgrading UserCredits tab otherwise UserCredits will not work properly.


Intro

UserCredits from Outerbridge is a plugin for WordPress which allows monetary amounts to be translated into credits for use on a website. Credits can then be used to perform certain operations on the site, such as accessing a restricted page on the website.

It is implemented on the website through the use of shortcodes. Shortcodes are special WordPress instructions encased within square brackets, e.g. [obr_display_balance], that can be used on pages and/or posts to make some complicated things happen.

The UserCredits plugin allows you to have an unlimited number of users and an unlimited number of credit bundles. You can set expiry dates for users' credits and there is even the option to automatically reset balances at specific intervals. Users can be given the option of transferring credits between themselves, and all users have access to their own transaction log history.

Please note that we refer to GBP in our examples but the UserCredits plugin is not dependent on any currency; you can use any currency you choose. Bundles can be set up for whole pounds (dollars, etc.) or one-hundredths, i.e. pence (cents, etc.).


New to UserCredits?

Follow the instructions on the Quickstart tab to get UserCredits up and running quickly.


Upgrading UserCredits

IMPORTANT: The UserCredits underwent a major rewrite for version 4.0. If you're upgrading from V3.x to V4.x, you MUST make the changes set out on the Upgrading UserCredits tab otherwise UserCredits will not work properly.


Need More Help?

If, having thoroughly read the documentation, you are still unsure and need further assistance, please contact us via our support desk and we will do our utmost to assist you. This is the only method of post-sales support. Please note that you will need your CodeCanyon purchase code.


New to UserCredits? Quickstart Guide

These are the key stages to setting up UserCredits:

  1. Installation
  2. General set-up
  3. Displaying balances
  4. Using credits around your site
  5. Setting up credit bundles
  6. Adding credits to users balances
  7. Transferring credits
  8. Customisation

Installation

To install UserCredits, first download the plugin (as a zip file) from your Downloads area in CodeCanyon and save a copy on your hard drive. Then select Add New from the Plugins menu on the WordPress dashboard. Then select Upload followed by Browse. When you have located and selected the zip file that you downloaded from CodeCanyon, click on the Install Now button. When completed, select the Activate option and UserCredits will be ready for configuration on your site.


General Set-Up

If you have installed the plugin correctly, there will be a UserCredits menu in the WordPress dashboard.

Click on the Set-Up page and review the 3 sections carefully.

  1. Section 1 (Setting up UserCredits to Allow Credits to be Purchased via a Payment System). If you want to use a payment system (e.g. PayPal, Stripe, GoCardless) to enable your users to buy credits, then you need to set up this section correctly. If you have purchased the UserCredits PayPal IPN Add-On, or you do not want to use a payment system, you do not need to complete this section.
  2. Section 2 (General Settings). Use this section to specify default settings for your site.
  3. Section 3 (Email Settings). Use this section to activate UserCredits' email notifications.

Visit the Custom Messages page to personalise the messages that UserCredits displays to your users.

Review each of the pages in the UserCredits area of the dashboard to see the new features and set-up your site.


Displaying Balances

To display the user's balance use the [obr_display_balance] shortcode on a page or post. Balances can also be displayed in the WP Admin bar at the top of the screen (use setting 2.4 on the Set-Up page) and/or in sidebars using the Display User's Balance widget which can be found under Appearance > Widgets.


Using Credits Around Your Site

To enable users to spend their credits on your site, use the [obr_check_credits] shortcode.

To create a link to a page where you want credits to be used, use the [obr_page_button] shortcode.

Use multiple [obr_page_button] shortcodes on the same page to create a "library" page.

The user will see a different button depending on whether they have previously paid for access to each individual page (providing that their access has not expired).

Example Set-Up

To illustrate how the site might be configured, let's consider the following situation, shown in the diagram below:

  1. We want a "library" page which has links to 3 sub-pages.
  2. It costs 10 credits to access page 1 for an hour (60 minutes).
  3. Buying page 2 gives access for 5 minutes and costs the default amount for the site, as specified in setting 2.2. on the Set-Up page.
  4. Page 3 costs 50 credits and access is for the number of minutes specified in setting 2.3 on the Set-Up page.

You can find more detailed information about how to use the shortcodes to create these features on the Shortcode tab.

using credits diagram


Setting Up Credit Bundles

If you are using a payment system, visit the Bundles page and set up your credit bundles.

Remember that bundles do not need to have a linear correlation, so you can offer more (or less!) credits for each extra amount that your users pay for access to your site.


Adding Credits to Users Balances

Credits are added using the [obr_add_credits] shortcode. The monetary amount is checked against the available bundles and (when matched) automatically adds the relevant number of credits to the user's balance.


Transferring Credits

To enable the transferring of credits between users, check setting 2.5 on the Set-Up page.


Customisation

Further customisation is available through the use of WordPress Action and Filter Hooks, please see the Advanced tab for more information.


Upgrading from an Earlier Version of UserCredits

UserCredits has undergone some big changes! We've listened to what our customers have asked for and we've completely re-written the plugin to give you lots of new and exciting features. Many of the old features have changed and/or been retired.

Here's a checklist of things that you'll need to do to be able to use the new version of UserCredits:

  1. Backup all files and the WP database before you make any changes.
  2. Review and replace all shortcodes using the following as a guide:
    Old Shortcode New Shortcode
    [obr_increase_credits] [obr_add_credits]
    [obr_credits_balance] [obr_display_balance]
    [obr_short_balance] [obr_display_balance]
    [obr_decrease_credits] [obr_check_credits]
    Please see the Shortcodes tab for more detailed information on the new shortcodes and their usage.
  3. Follow the instructions on the Quickstart tab to get UserCredits upgraded and running smoothly.

Shortcodes

UserCredits is implemented via the shortcodes below.

You can type the shortcodes into a post or page, or, if you are using the Visual Editor, most shortcodes are available as a button. Hover over the buttons to see which shortcodes are available, and click on the shortcode to see information on key parameters and usage.

Parameters are used to modify the default behaviour of the shortcode, for example, [obr_display_balance showexpiry=true] will ensure that expiry dates are shown when displaying a balance. Parameters can be listed in any order after the shortcode name, but must be included before the ] symbol at the end of the shortcode.

Shortcode Purpose Parameters
[obr_display_balance]

The [obr_display_balance] shortcode is used to display the user's credit balance on a page.

This shortcode has a button in the visual editor.

There are four parameters available:

  1. short. Optional. Example usage: short=true. Displays just the number of credits, allowing you to add it into text on a page, e.g. <p>Credit balance: [obr_display_balance short=true]</p>
  2. singular. Optional. Default value: You have 1 credit. Example usage: singular="You currently have a balance of 1 credit.". This is the message displayed when the user has one credit. Setting the parameter in the shortcode overwrites the global setting specificed in section 2 of the Custom Messages page.
  3. plural. Optional. Default value: You have %d credits. Example usage: plural="You currently have a balance of %d credits.". This is the message displayed when the user has any number of credits other than one. %d in the message will be replaced with the number of credits available. Setting the parameter in the shortcode overwrites the global setting specificed in section 2 of the Custom Messages page.
  4. showexpiry. Optional. Example usage: showexpiry=true. Returns an expiry date (if there is one) in addition to the credits balance. Please note that this parameter has no effect if the short parameter is set to true.

With the singular and plural options above, to include an expiry date you will need to include reference to it in your message text string, e.g. "You have 1 credit which expires on %s." and "You have %d credits which expire on %s.".
[obr_page_button]

The [obr_page_button] shortcode is used to create a button linking through to a specific page with restricted access. Multiple instances of this shortcode can be put on one page to create links to a library of pages. Each button can be in one of two states depending on whether:

  1. The user has access to the page with restricted content; or
  2. The user does not have access to the page with restricted content.

This shortcode has a button in the visual editor.

There are three parameters available:

  1. pageid. Mandatory. Example usage: pageid=862. Used to identify which page with restricted content is being referred to. To identify the WordPress page or post id to use, go to the Post or Pages menu, and hover over the edit option to see the page id in the bar at the bottom of your browser.
  2. access. Optional. Default value: Open Page. Example usage: access="Go To Page". This is the message displayed on the button when the user has already used credits to access the specific page or post.
  3. noaccess: Optional. Default value: Page Preview. Example usage: noaccess="Find Out More". This is the message displayed on the button when the user has not used credits to access the specific page or post, or when previous access to the page has expired.

Please note that to assist with styling the buttons (in your theme), the following CSS classes are automatically added to the page buttons depending on their state:

  1. When the user has access to the page with restricted content, the button has a CSS class of "green-button"; or
  2. When the user does not have access to the page with restricted content, the button has a CSS class of "red-button".

Additionally, all buttons created by this shortcode have a CSS class of "page-button" as well.
[obr_check_credits]

The [obr_check_credits] shortcode is used to restrict specific page content access only to users who have purchased access using their credits.

The [obr_end_preview] divider can be used within the shortcode to separate the preview part of the page from the protected course content.

This shortcode has a button in the visual editor.

There are two parameters available:

  1. accesscost. Optional. Example usage: accesscost=25. This parameter allows you to vary the cost of a page from the default set in setting 2.2 on the Set-Up page.
  2. expiryminutes. Optional. Example usage: expiryminutes=10. This parameter allows you to vary the expiry period of a page from the default set in setting 2.3 on the Set-Up page. The number used represents the number of minutes access to the page; set this parameter to zero to give unlimited access to the page.

Please note that this is an enclosing shortcode, so an example of the correct usage is as follows:

[obr_check_credits]
Page content to be visible only to users who have used credits to access the page.
[/obr_check_credits]

To include a preview of the page content, structure the [obr_check_credits] shortcode as follows, using the [obr_end_preview] divider:

[obr_check_credits]
Preview or teaser which is visible only to users who haven't used credits to access the page.
[obr_end_preview]
Page content which is visible only to users who have used credits to access the page.
[/obr_check_credits]
[obr_add_credits]

The [obr_add_credits] shortcode is used to process a monetary amount and to translate it into a credit balance.

The monetary amount is checked against the available bundles and when matched adds the relevant number of credits to the user's balance.

This shortcode has a button in the visual editor.

There are no parameters for use with this shortcode.

You must set-up the two variables which are defined in Section 1 of the Set-Up page for this shortcode to work correctly.

Advanced users may wish to review the "obr_txn_check" and "obr_added_credits" hooks for additional processing options; see the Advanced tab for more information.
[obr_low_credits_email_alert]

The [obr_low_credits_email_alert] shortcode is not normally used, as this function is automated via setting 3.1 on the Set-Up page. However, if your WordPress cron scheduler is not working correctly, this shortcode can be called; it will review all balances and send an email to those users with a balance below the default specified on the Set-Up page.

Please note that this shortcode does not have a button in the visual editor.

There are no parameters for use with this shortcode.
[obr_credits_added_email_alert]

The [obr_credits_added_email_alert] shortcode is not normally used, as this function is automated via setting 3.2 on the Set-Up page. However, if your WordPress cron scheduler is not working correctly, this shortcode can be called; it will review all user accounts and send an email to inform those users that have had credits added since the last reminder that they have a credits balance available for use.

Please note that this shortcode does not have a button in the visual editor.

There are no parameters for use with this shortcode.
[obr_balance_update_email_alert]

The [obr_balance_update_email_alert] shortcode is not normally used, as this function is automated via setting 3.3 on the Set-Up page. However, if your WordPress cron scheduler is not working correctly, this shortcode can be called; it will send an email to all users showing their credits balance.

Please note that this shortcode does not have a button in the visual editor.

There are no parameters for use with this shortcode.

Advanced

Action and Filter Hooks

Advanced users may wish to further customise their installation of UserCredits. To help you with this we've added a helpful range of action and filter hooks.

WordPress hooks allow plugins like UserCredits to "hook" into the rest of WordPress; i.e. to call functions in your plugin at specific times, letting you add your own custom functions to the plugin. UserCredits' specific hooks are detailed in the table below.

To set up a hook, you will need to add a function calling the hook to your functions.php file in your active theme. Here's an example which sends an email containing the data passed to the admin email address of the site:

function creditsadded($input){
	// my customised function
	wp_mail(get_option('admin_email'), 'obr_added_credits example', json_encode($input));
}
add_action('obr_added_credits', 'creditsadded');

Available Hooks:

Hook Type Data Passed Description
obr_txn_check Filter

$input['valid_txn'] contains whether the transaction is valid - the value is set to true unless modified by your custom processing

$input['userid'] contains the WordPress user id

$input['amount'] contains the amount of the transaction

$input['txn_id'] contains the transaction id reference

$input['credits'] contains the number of credits to be added

$input['expiry'] contains the expiry of the credits

A valid transaction is one where the transaction id has not been duplicated and the monetary amount matches that of a credit bundle.

This filter hook can be used to add further custom processing to an otherwise valid transaction.

When the custom processing has been completed, the value of $input['valid_txn'] is used to decide whether the credits will be added or not. If the transaction fails, the message in setting 1.6 of the Custom Messages page will be displayed.

To fail the transaction check, return an amount of $input['valid_txn'] = false;
obr_added_credits Action

$input['userid'] contains the WordPress user id

$input['amount'] contains the amount received

$input['credits'] contains the number of credits being added

$input['txn_id'] contains the transaction id reference

$input['newbalance'] contains the user's credit balance after the transaction

$input['expiry'] contains the expiry date of the credits

The "obr_added_credits" action is executed immediately after credits are added to a user's balance.
obr_user_registered Action

$input['userid'] contains the WordPress user id

$input['credits'] contains the number of credits being added

$input['txn_id'] contains the transaction id reference

This action is performed after a user has been registered and the default number of credits have been added.
obr_credits_redeemed Action

$input['userid'] contains the WordPress user id

$input['credits'] contains the number of credits that the page access cost

$input['txn_id'] contains the transaction id reference

$input['newbalance'] contains the user's credit balance after the transaction

$input['expiry'] contains the expiry date of the page

 This action is performed after page access has been purchased.

Learn more about WordPress' API here.

Watch this space as we're planning on releasing more hooks in future releases.