Documentation "Avia Support Envato" Extension Plugin


Content:

General Information:

This plugin is an extension to the "Avia Support"-Plugin (and bbPress).

The main task is to implement the Envato Support Policy with limited support time and give moderators information about the products, licenses and support expiration dates of the users products when answering support requests.

For each of your Envato products you can select free or limited access and assign them to one (or multiple) forums.

User account and user product management supports login via Envato account with "Envato User Name" (with fully automatic synchronisation of the products the user has bought), login with forum user name and manual product managment or a mixture of both. It is possible to hide Envato user name and E-Mail in the forum. Registration can be done automatically (via Envato account) on first login or with a registration form.

The features and the usage are described in the following sections.

Several options allow customizing the features of this plugin and make it very flexible.

Activation, Setup, Deactivation, Uninstall

This plugin is based on the plugin "Avia Support" (which depends on bbPress). Both plugins must be activated.
We recommend to avoid the bulk features of WP on the plugin page with these plugins. Use plugin specific operations instead and use the following order:

Activating the plugin and Setup:

We describe the steps for a complete new setup of all plugins (steps can be skipped if the base plugins are already running).

Deactivating the plugin:

  • Dectivate this plugins
  • Dectivate all other depending plugins, if you want to deactivate Avia Support
  • Dectivate Avia Support
  • Dectivate bbPress

Deleting the plugin:

  • Delete this plugins
  • Delete all other depending plugins, if you want to delete Avia Support
  • Delete Avia Support
  • Delete bbPress

The Envato Connection

To access Envato we use the new Envato API:

Read the information there to get a better understanding and follow the steps below to create the application, personal token key and link this plugin to Envato.

Make sure, you are logged in at Envato with the correct user account. In case you have several user accounts, open a new private window to force a new login at Envato. Envato stores the last login details in cookies and takes this account information. Instead of the new private window you can also clear all cookies or all cookies in connection with envato (envato.com, account.envato.com, api.envato.com) to force a new login at Envato.

Register your application

Click here to open the register application page

App name: You can choose any name you like.
Required permissions: You have to check the following options:

  • View and search Envato sites
  • View the user’s Envato Account username
  • View the user’s email address
  • Verify purchases the user has made
  • View the user’s purchases of the app creator’s items
  • List purchases the user has made
Confirmation URL: The confirmation url is the base url of the site, where this plugin is activated and MUST end with "?av_supp_envato_login=confirm" (e.g. http://www.example.com?av_supp_envato_login=confirm). You MUST enter it at Envato and in our plugin option exactly the same, otherwise we cannot establish a connection to Envato when a user logs in with his Envato user name. We have to pass this URL to Envato, Envato checks it and makes a callback to this URL. The query string variable is needed by our plugin to clearly identify the callback from Envato API – if this is missing, the plugin will not accept the callback.’

Click Register App button and you are redirected to a "Success Page". Copy the Secret key to a safe place, you will need it in our options page.

Here you find your applications and OAuth client ID’s and you can edit permissons.

Create your Personal Token Key

Click here to open the create token page

Token name: You can choose any name you like.
Required permissions: You have to check the following options:

  • View and search Envato sites
  • View your Envato Account username
  • View your email address
  • View your items’ sales history
  • Verify purchases of your items
  • View your purchases of the app creator’s items

Click Create Token button and you are redirected to a "Success Page". Copy the Secret key to a safe place, you will need it in our options page.

Here you find your tokens and you can edit permissons.

Set the plugin Envato Connection options

Then go to WP Dashboard->AviaSupport->EnvatoAddOn and look for section Envato Connection Details.

Personal Token ID:: Enter the token name you used to create the token. This is only to save this information for later, it is not needed at the moment.
Personal Token Key: This is the secret key returned by Envato for the personal token (do not mix up with application secret key)
Application – OAuth client ID: Look here for the Application name you registered and below you find OAuth client ID:. Copy the value.
Application – Client Secret Key: This is the secret key returned by Envato for the application (do not mix up with personal token secret key)
Confirmation URL: The confirmation url is the base url of the site, where this plugin is activated and MUST end with "?av_supp_envato_login=confirm" (e.g. http://www.example.com?av_supp_envato_login=confirm). You MUST enter it at Envato and in our plugin option exactly the same, otherwise we cannot establish a connection to Envato when a user logs in with his Envato user name. We have to pass this URL to Envato, Envato checks it and makes a callback to this URL. The query string variable is needed by our plugin to clearly identify the callback from Envato API – if this is missing, the plugin will not accept the callback.’

Envato products and support time restrictions

This plugin adds "Envato Products…" submenus to WP dashboard "Avia Support" menu.

Envato Product Management features:

  • Scans your products on Envato Market Place and store information about them locally, add new products when found
  • Assign products to have "Limited Support Time" or "Free Support"
  • Assign products to 1 or more forum(s) -> limit access to a forum depending on the products a user has bought
  • New products are automatically assigned to a forum that start with the product name

Initialise and update your products:

  • Goto WP Dashboard -> Avia Support -> All Envato Products: Opens a table of all your Envato products our plugin knows.
  • Click button "Sync Products with Envato" on top of the table to get all your products (you have to do this everytime you add new products at Envato or you want to update saved product information). Please be patient, this may take some time depending on the amount of products you have.
  • Forums are assigned automatically to new products, when Envato Theme Name (found in [‘wordpress_theme_metadata’][‘theme_name’]) starts in a forumname. Settings for already existing products are not changed.
  • Manually assign the forums to products (quick edit is supported), you may assign multiple forums to a product or multiple products to a forum. And set the support time restriction.
  • You also can add products manually to the list. Enter the unique Envato product ID and this product is assigned to the Envato product.

User account management and support policy

User Account Management features:

  • Login to the support forum with the Envato Account. User is identified with his unique Envato user ID. For a new user, if Envato username and E-Mail exist in our forum, this user is assigned to the Envato user (with the unique Envato user ID). Otherwise we create a new account for the user with Envato user name as forum user name, Envato E-Mail as forum E-Mail and an autogenerated forum password.
  • Register a new user in the forum with a purchase code from Envato (User can get access to our forum without giving us access to his envato account)
  • Login to the forum with a forum user name (user is free to decide which way to login – also as a fallback if Envato API is down)
  • Change the forum user name and E-Mail (allows to hide the Envato user name and E-Mail in the forum)
  • Deleting a user account with all topics and replies is already part of Avia Support plugin
  • Manually assign the unique Envato User ID to an existing user account or detach an account from the Envato account by removing this ID
  • Customizable welcome subscription E-mail with the generated password
  • Customizable shortcode for the login form (intended to be used in a plain text widget in the sidebar)
  • Customizable shortcode for a "Register New Account" form (intended to be used on a page to provide additional information for new users)

User Product Management features:

  • When user logs in with his Envato Account, we scan and synchronise all his products with Envato. New products are added.
  • All relevant information about products are saved locally to reduce Envato API calls.
  • Manually add user products to the local list with the purchase code or delete products from the list (if the user does not want to login with his Envato user name, he, a moderator or keymaster (option) can manually manage his products).
  • When user logs in with the forum name, only products in the list can be synchronised – new products are not recognised.
  • A built in logic reduces Envato API calls for synchronisation to a minimum.
  • Start a synchronisation manually, if necessary (e.g. user bought a new support ticket, but the synchronisation logic blocks). A button is found on the User Profile Edit Page in frontend. Be aware, that new products are only recognized, if user logs in with his Envato account.

Product synchronization logic:

To understand some of the options you need some background information about the synchronization logic and limitations:

User logs in with Envato user name:

Users may change their Envato user name and E-Mail. Therefore we use the unique Envato user ID to assign a forum user to an Envato user. This ID is currently only available, when we scan the user’s products right after the user logged in an gave us access to his account. The API only allows us a paged query, returns a number of products, but no further information about more remaining products.

For users with few products there is a great chance that we got all products, but not for users with many products.

To avoid unnecessary time consuming API calls for a new user we get all products and add a timestamp with the last synchronisation time to each product. On following logins we limit to one API call. A complete synchronisation is started again, if synchronisation of one product dates back a given period (option "Force autosync of products (in days)") – in that case we also can add new products to our internal user’s product list.

User logs in with forum user name:

We only can synchronise the products in our internal user’s product list – we cannot access new products (user can add new products manually). To avoid unnecessary time consuming API calls we also use the timestamp (and option "Force autosync of products (in days)") to start a new synchronisation, if one product dates back that period of days.

Exceptional cases:

  • A product is getting close to expire of support time (option Sync products not before expire): When a product’s support time passes that number of days before expire, we check regularly, if user bought a new support time.
  • A product’s support time is expired (option Force autosync of already expired products): For products with expired support time we check in this period of days, if user has bought a new support ticket.

Managing User Account and Product Data:

Following data can be maintained:

  • WP Login Name: Allows to hide Envato Username in the forum.
  • Envato ID: Allows to detach or attach a forum account to an Envato account.
  • Delete Products: Manually delete purchase codes (= products) from an account.
  • Add Products: Manually add purchase codes (= products) to an account.

Data can be maintained by:

  • Users may change only their own data
  • Moderators can change all data (depending on a setting in Avia Support moderators may get access to user edit pages !!)
  • Keymaster and WP Admins can change all data

The features can be accessed:

  • Frontend: User Profile Edit Page
  • Backend: "User Profile Page" or "Edit User Page"

Options allow to limit access individually to each of these management features.

Support Policy features:

  • Show user a list of his products with license and support time status in login form.
  • Show users a special warning message before a product support time ends in login form and topic page.
  • Block users from creating topics and replies for a product, when not in support time for a product.
  • Show moderators all products of a user with expiration date and licenses when answering a topic.

Plugin options

Goto WP Dashboard -> Avia Support -> Settings -> Tabs "General" or "Envato AddOn"

The following options can be set on tab "Envato AddOn" section "Frontend User Settings:":

Allow User login to forum:
  • Always
  • With at least one product
  • When a product is in support time

Giving access to the forum allows the user to login. Forum settings or expired support time can block creating a new topic or a reply. If the user is not allowed to login, he is logged out immediatly even if he has a valid account and a valid password on login.

Show support expires warning (in days): Products of a customer have a support time expire date. This is the number of days before expiration date to show an extra warning message to the user.
Sync products not before expire (in days): These are the number of days before end of support time for a product, when we start a synchronization of our locally stored product(s) with Envato to check, if user has bought an additional support ticket.
Force autosync of products (in days): These are the number of days to pass to force the next synchronization with Envato.
Force autosync of already expired products (in days): Expired products are excluded from time check for the next synchronisation. These are the number of days to pass for expired products to force the next synchronization.
Route Register New Account to page: The shortcode handler for the login form has a parameter "register_forum_link". If you set "register_forum_link=option" you activate this option, otherwise it is ignored.

  • Select a page to reroute
  • "Do not allow to register" disables to register completely
  • ‘Use integrated default form’ uses the default built in "register new account" in the login form.

The following options can be set on tab "Envato AddOn" section "User Profile Editing:":

Allow change of WP loginname;


Allow change of Envato ID;


Allow deleting products;


Allow adding products:
  • Never
  • User
  • Moderator
  • Keymaster, WP-Admin

You can give access to these capabilities independently. Moderators must be given capability in Avia Support plugin to get access to the user pages. Can be accessed in frontend and backend.

The login form

Intended to be used in the sidebar (plain text widget):

Shortcode: [avia_supp_envatosc_login_form]

The shortcode alone generates a fully functional loginform. A description of the possible parameters and the default values can be found in avia-support-envato\classes\class-avia-support-envato-login.php in function handler_sc_login_form.

"Login with Envato account" – button:

  • Redirects to "Envato User Login" page
  • User logs in at Envato and confirms to give us access to his Envato data
  • Envato returns and we get access to the unique Envato user ID
    • Existing user (= Envato user ID exists): is logged in (if allowed to)
    • Envato Username and Envato E-Mail exist: forum user is assigned to Envato user (with the unique Envato user ID) and is logged in (if allowed to)
    • New user: We create a new account with forum user name = Envato user name and the Envato E-Mail and send the user a subscription E-Mail with the forum password, get all his products from Envato and user is logged in (if allowed to)
  • Complete user product list is synchronised (if not blocked by logic) and product information is displayed

"Login" – button:

  • User enters Forum login name and password
  • Redirect to standard WP login procedure, performs login and returns to the current page
  • Plugin checks, if user is allowed to log in – if not -> logout immediatly
  • Stored user product list is synchronised (if not blocked by logic) and product information is displayed.

Additional link buttons

The following additional links can be displayed beside the login button:

Register New Account:

Supports following features (set with shortcode parameters):

  • Autogenerate password (auto_generate_pwd): Disable, force or let user select with a checkbox
  • Login after autogenerated password (login_on_auto_generate): Enable/disable
  • Allow to register without a purchase code (does not mean, that user gets access to a forum) (need_purchase_code)

Depending on the setting of the shortcode parameter "register_forum_link":

(empty string) Supress the link
# Use the implemented ajax register fields: Shows additional inputfields to enter E-Mail and purchase code and a possible checkbox to autogenerate a password
option use setting of the option field "Route Register New Account to page:"
(url) Link to a page with the "Register New Account" form

Register New Product:

Depending on the setting of the shortcode parameter "register_new_product":

yes Adds a purchase code field to add a new purchase code to the user account to be able to login, when all products are expired and user does not want to use his Envato account for login.
no Suppress the link

Lost Password:

Depending on the setting of the shortcode parameter "lost_password_link":

(empty string) use standard WP redirect to the lost password page
(url) Link to a custom lost password page

The "Register New Account" page

Intended to be used in a page.

Supports following features (set with shortcode parameters):

  • Autogenerate password (auto_generate_pwd): Disable, force or let user select with a checkbox
  • Login after autogenerated password (login_on_auto_generate): Enable/disable
  • Allow to register without a purchase code (does not mean, that user gets access to a forum) (need_purchase_code)

Shortcode: [avia_supp_envatosc_new_account_form]

The shortcode alone generates a fully functional form. A description of the possible parameters and the default values can be found in avia-support-envato\classes\class-avia-support-envato-login.php in function handler_sc_new_account_form.

The function and shortcode parameters are similar to Register new account in the Login form.

After registration the user is redirected to the previous page (or a page set in shortcode parameter).

Developer Section

This section contains useful inside code information.

Options

Options for this plugin are stored in associative arrays. To avoid calls to isset, to ensure startup default values and to make customization easier loading the options are handled in functions, where it is possible to filter the option array and values on loading the options:

  • class Avia_Support_Envato::get_options_default

Debugging this plugin

If your debugging server can recieve callbacks from the Envato server, you can skip this section.

To debug Envato API calls that require the user to login with his Envato Account (OAuth authentication) on a server that cannot recieve the Envato API confirmation URL (e.g. localhost) follow the following steps:

  1. Set up a testserver that can be reached with the Envato API confirmation URL.
  2. Install WP, bbPress, Avia Support and AviaSupport Envato on this server and activate all.
  3. Acitvate WP_DEBUG in wp_config.php (not recommended in a production environment, therefore a testserver): define(‘WP_DEBUG’, true);
  4. Set the Envato Connections in the testserver
  5. Setup the testserver, that your testusers are able to login (easiest set option "Allow User login to forum:" to "always")
  6. Set the Envato Connections in the debugging server
  7. Set define(‘WP_DEBUG’, true); in the debugging server
  8. When WP_DEBUG = true you find a button "Login hardcoded" in the loginform below the button "Login with Envato account". Only use this button on the debugging server !!!!
  9. Let a user login with his Envato Account on the testserver
  10. After a successfull login below the logout button you find a section "Envato" with a list of internal envato keys.
  11. On your debugging server open file: avia-support-envato\envato\class-avia-envato-api.php and line 23 – 26 you find constants:
    • HD_ACCESS_TOKEN
    • HD_TOKEN_TYPE
    • HD_REFRESH_TOKEN
    • HD_EXPIRES
  12. Copy the values from the testserver page to these const values and save the file.
  13. On your debugging server click "Login hardcoded". The copied values simulate to be recieved by Envato, are stored in the local envato object and you can continue as if you have recieved these values directly.
  14. The refreshing of expired keys does not work properly on the debug server, so if the keys expire, you have to login again on the testserver and copy the new values to your debugging server and login again on the debugging server.

For debugging requests with personal token you only have to set the Envato connection options correctly. You do not need to do the steps above.