Subscriptions

This plug-in will add subscription system to your Vivvo site, allowing you to make parts of your site accessable only to multiple levels of paying members.

You can define your own subscription packages, with different privileges , prices and durations, and choose between a number of supported payment gateways. Subscriptions can be automatically activated or set to wait for you to manually approve them, as additional protection against fraud.

You need to manually modify one of administration templates in Vivvo admin folder. Locate the file: VIVVO_ROOT/VIVVO_ADMIN_DIR/templates/users/group_content.xml and find the following code (around line 101):

<vte:include file="{VIVVO_FS_ADMIN_DIR}templates/gui/html_radio_yes_no.xml" label="{LNG_ADMIN_UPLOAD}" name="UPLOAD" value="{group.group_privileges[UPLOAD]}" tooltip="{LNG_ADMIN_USER_GROUP_TOOLTIP_3}" />

and add the following piece of code below that line:

<vte:lang src="plugins/subscriptions/admin/lang/" />
<vte:include file="{VIVVO_FS_ADMIN_DIR}templates/gui/html_radio_yes_no.xml" label="{LNG_PLUGIN_SUBSCRIPTION_SUBSCRIPTION_REQUIRED}" name="SUBSCRIPTION" value="{group.group_privileges[SUBSCRIPTION]}" tooltip="{LNG_PLUGIN_SUBSCRIPTION_TOOLTIP}" />

This will add option to Vivvo administration to choose which groups will require subscription.

After you have completed this step, you can install the plug-in the usual way, as detailed in the next section.

You need to access the Plug-ins section. Click on the Plug-ins link which is located in Main menu at the top of your administrator panel.

A list of all plug-ins currently registered to the system is displayed on the right hand side of the screen on Downloaded plug-ins tab.

To install Subscriptions plug-in you need to click on the install icon on the right side of the plug-ins name.

This will take you to the page with the installation link: Click here to Install the plug-in

After you run the installation, you will be informed that the plug-in was successfully installed.

You may easily go back to the Plug-ins page, by following the link: Click here to go to Plug-in page:

To uninstall Subscriptions plug-in you need to click on the uninstall icon on the right side of the plug-in name.

This will take you to the page with the link for uninstall: Click here to uninstall the plug-in

You will be informed that the plug-in was successfully uninstalled and you may return to the Plug-ins page by clicking the link: Click here to return to Plug-in home page.

In order to integrate subscriptions plug-in with Vivvo, we need to adjust default Vivvo settings for user groups. These settings very much depend on particular subscription setup that we aim for, so it's very important to have a good understanding of Vivvo's system of privileges first.

Each user in Vivvo belongs to one or more user groups (e.g. Editor, Writer, Member, Guest, etc..). Vivvo controls access to various parts of the site by controlling privileges of each of these groups, that is a group can be given certain rights, and they will be automatically applied to all users belonging to that group.

In order to create content that will be accessible only to paying members, we first need to create categories that will hold those articles. All articles inside those categories will be visible only to subscribers, while the rest of the site will be still visible to general public.

For example, lets say that you are running website about cooking, and you want to make your recipes available only to your subscribers. You could create a new category named Recipes, to hold your premium content. Next we need to do is to make sure that regular users can't access this category. By regular users we mean users that don't belong to site stuff, that is users in groups Member or Guest. We need to go to Vivvo administration, to Users section, and edit settings for these two groups. We will first edit Member group:

and now remove (unselect) read privileges for Recipes category

Save these settings and repeat the same steps for Guest group.

Now, if guest or member visitor goes to an article in category Recipes, she will not be able to access the content inside this category.

Next thing we need to do is to define a user group to hold our subscribers, so that we can define their privileges. We may create a new user group or we can use an existing group, let's say we create a new group named 'Premium access'. We need to go to Users section of Vivvo administration and edit options for this group:

First we want to allow this group to read the premium content, so in our example we need to give this group right to read from our Recipes category:

Also, on the bottom of the screen you will see the option 'Subscription required', we should select it to define that this group requires subscription for access:

Just click Next for next few screens, and then click Save to save the settings.

With these steps we have done 2 important things:

• Blocked access to our premium content to general public
• Given access to our future subscribers

Let's go to Plug-ins section, and there click on Subscriptions link to access plugin administration.

In the central area you can see the entries from subscription log for last 24 hours period. This will give you the handy overview of all recent signups, payments and subscriptions that have been canceled. This list gives just a short overview, and to get all available details on transactions you can click on Download log button, to download the full list of subscription related events for current month.

In menu on left hand side you've got the following options:

• Quick link - contains links to the most common operations
  • Gateways - it will open window with Gateways options
  • User groups - list of all user groups that require subscription. Clicking on the name of the group will list all users in that group, while icon on the right hand side will open group settings panel

• Preferences - General preferences, apply to all user groups
  • Currency - the currency you wish to use as default for all payments
  • Mode - allows you to put Subscriptions in Sandbox test mode, to test the system without making any real payments
  • Thank you mail - text for mail that is sent out to users upon subscribing to a package for the first time
  • Notification mail - text for mail that is sent out to users each time payment is made (useful for recurring payments)

• Search - allows you to search subscribers by their name, subscription status and/or group they are subscribed to

Lets first set preferences for subscriptions. We will choose to use US dollars, and subscriptions will be in sandbox test mode for now, to make sure no real payments take place until we setup and test everything. On this page you can also define text for emails that will be sent to users upon registration. Welcome mail is sent on sign up, and notification email is sent each time subscription payment is done. We will leave text for welcome and notification emails empty for now, which will disable sending out the mails.

Next we need to define the settings for each subscription user group. In our example there is only one group, so lets click on little pencil icon next to it's name to edit the settings for Premium content group

We will get the following screen:

Here you can define what categories will your subscribers have access to read, and also you can define subscription package (or packages). If you check recurring option and, if selected gateway supports recurring payments, customer will be automatically charged this fee on the end of each subscription period. Some gateways don't support recurring payments, and in those cases payment will be regular one-time fee. Approval required option defines if subscription will be automatically activated upon successful payment is made, or subscription will be marked as pending, and you will have to activate it manually (option for fraud protection).

For this example, we can define one 5 days package that will cost $20, it will be one-time fee, and will be automatically activated after the payment:

To add another package click on Add package link:

Lets define another package with price $50, one month period, recurring payments are on, and manual approval required:

If you wish to delete a single package from the list click on small red X icon next to the package, or you can clear the whole list by clicking on Delete all packages link.

After you have defined a list of all subscription packages for this group click on Save button to save the settings.

Next step is to decide which of the supported payment gateways you wish to use, and to setup setting for each of them.

If you go to Quick link tab and click on Gateways link you will get a list of all payment gateways currently supported. In order to be able to use certain gateway, you need to activate it, by selecting one or more gateways in the list

and then selecting Active option from the list

To disable a gateway select Inactive option.

You need to edit settings for each gateway that you plan to use, in order to provide logon and other gateway specific information. You can do that by clicking on edit button

You will be presented with form where you can edit settings for that particular payment processor. This settings are specific for each payment gateway.

In this form you need to enter your PayPal account login, either email or account ID. For security reasons we highly recommend that you use account ID for this. You can obtain this ID by logging in you PayPal account, and then going to Profile page and you'll see “Secure Merchant Account ID” on the top of the page. This filed is required, since without this value payments over Paypal gateway will not work.

Optionally, on this page you can also select a custom image for the payment button, if you wish. It will be used instead of regular “Subscribe” button.

The first two fields are required. Account ID is your Merchant ID, and to get Secret word log-in to your 2CO account, and then go to Look & Feel page.

Optionally, you can also select a custom image for the payment button, to use instead of 2CO button.

Required fields are:

• API Login ID and API Transaction Key - To get this data login to you Authorise.Net account, go to Account > Settings and then click on 'API Login ID and Transaction Key' link
• MD5-Hash - go to Account > Settings and then click on 'MD5-Hash' link

Optionally, select a custom image for the payment button, to use instead of Authorize.Net payment button.

After you have setup everything you should put Subscriptions plugin into test mode, in order to make sure that everything works the way you planned. To do this go to Preferences tab on Subscriptions plugin page, select Sandbox option and save the preferences.

Next thing you should do is to test the subscription process. To do this you need a new user, that will represent average visitor to your site. Go to Users menu, and create a new regular user. After creating that user log out of admin account, login as that new user, and go to pages on your site that require subscription. If setup is ok you should be presented with the follwoing screen, that explains that you need to subscribe in order to access those pages.

After clicking on the button you will be taken to the next page where you will be given payment options. Depending on your setup you will see all the packages for requested content and all active payment gateways. After choosing the payment option you will be given order summary, and a button that you need to click in order to make a payment. For example, in case of PayPal gateway that looks like this:

As Subscriptions plugin is in the test mode you can freely click on the payment button, and then follow the instructions from the payment gateway site to finish demo payment. No real money will be charged during this process. After finishing the payment and returning to your site, your new user will have new privileges as a paying subscriber. The activation of subscription is not immediate as we have to wait for confirmation of successful transaction from payment gateway, but it usually takes less then 5 minutes.

You can than log-in as administrator user again, and on Subscription plugin page you will see in the transaction log when transaction is finished. Only a short summary of transaction is shown here, if you need more detailed log, you can download the full log by clicking on Download log button.

If you click on the name of the group that your new user has subscribed, you will get a list of all users subscribed to this group.

You can also search users more directly by using Search tab.

On this screen you can also delete users from the system, or remove them from this group, which will effectively remove their privileges to the premium content.

In case you used Pending subscription option in your payment packages, users' subscriptions will not be activated automatically. This users will have a different icon in front of their name

In order to activate their subscription, select them in the list and then select Activate subscription action from a drop down

If you need more details on user subscriptions, click on edit icon, on the right hand side of the list, and you will get the form where you can see what package user has, what gateway it was paid over, and when it expires. On this form it's also possible to edit expiry date, in case you wish manually to select it.

Once you are sure that subscriptions are setup the way you want, you can turn plug-in into Live mode.

• PayPal payment processor has a limitation on length of subscription periods, so if you plan on using it please take this into account when defining payment packages. Maximum supported periods are:
  • 90 days
  • 24 months
  • 5 years
• If you use non-English characters for subscription groups, you need to change settings on your PayPal account, to add support for UTF-8 encoding. Login to PayPal site, and go to Profile > Language Encoding. Click on More options, and for Encoding select UTF-8.

• Currently recurring payments are not supported.

• Currently recurring payments are not supported.
• Gateway supports only US dollars as currency and has no support for non-English characters

For developer guide on adding new processor to Subscriptions plugin, please refer to this wiki devdoc page.