WooCommerce Plugin for the Xibo Platform


#1

The WooCommerce Plugin for the Xibo Platform allows the holder of a valid reseller account access, through the Xibo API in order to provide Xibo Platform products within their own WooCommerce website. WooCommerce will be shortened to WC from here onward.

The plugin is available on a per-project basis for a licence fee, please contact us to discuss your requirements.

Installation

The plugin is a Wordpress plugin - you will have been provided a ZIP file containing the plugin files. Extract this in your wp-content/plugins folder.

Navigate to your Wordpress plugin’s page and activate the Xibo WC plugin.

Configuration

Once the plugin is activated it must be configured on the WC Settings Integrations tab. There are 4 settings required:

  • API Key
  • API Secret
  • Production?
  • Logging?

The API key/secret are available from the customer portal “My Account” page under the integrations tab. You will have a different key/secret in the live and test sites, please ensure you are using the correct key. Transactions in the live site will result in real transactions occurring in the platform and against your registered credit card - these transactions are legally binding, as if you had placed them through the website. Please make sure you are using the correct keys and do all testing in “test” mode.

If your keys are invalid, an error message is presented in the user interface:

When logging is enabled, logs can be viewed on the WC system status pages, under the logging tab.

Logging is verbose and should be switched off by default.

Product Configuration

Products should be added to WC to accurately represent your chosen sales model and then optionally enhanced with Xibo Platform integration.

Each product configuration page will present a new drop down select box containing a list of supported Xibo Platform products. Select the applicable product and save in WC, when the page refreshes any additional options required by the Xibo Platform will be presented for configuration.

Xibo for Android Licences

Xibo for Android Licences are “Simple Products” in WC terms. A bundled product can also be defined as “Xibo for Android” if you want it to include a licence (for example if you are selling an Android device including a licence).

There are no product specific configuration options for this product. A licence pool email address will be collected at checkout.

If you have the WC commercial addon for defining product bundles (chained products), the Xibo for Android product can be included in a bundle.

Xibo in the Cloud CMS

This product relies on WC Product Variations, which are used to configure the Domain, Theme and Region which should be applied to the order. A “variable” product should be added and configured with an attribute to be used for Variations.

Each variation configured exposes select boxes which are presented on the product variations tab to select these values:

At checkout the user will be prompted to pick an existing CMS instance (if they are logged in) or enter a new one on checkout.

Spring Signage will generate a renewal invoice and email the API account holder (this process is not automated). It is the 3rd parties responsibility to manage the renewal of the CMS within WC or the payment processor they have selected. The WC Subscriptions addon could be used for this product to achieve this.

Checkout

The Checkout process is enhanced for Carts containing Xibo Platform products in order to collect any additional information required.

When the presence of one or more Xibo Platform products is detected the fields will be presented after the order notes. If the user “Checks out” the presence of these fields is validated.

Assuming the cart is valid the order completes in the usual WC process, which is dependent on the payment processors that are enabled. At some point in the future - assuming the payment was successful - the order will transition into the Processing or Complete states.

The fields added to this page after order notes come with some standard descriptive text to help the user understand what the field is for. Alternative text can be provided by adding a filter to the active Wordpress theme.

The following filters are available:

  • xibo_woocommerce_xfa_licence_email_message: Form field message for entering a Xibo for Android licence pool email address.
  • xibo_woocommerce_xfa_licence_email_error: Validation message when the Xibo for Android licence pool email address is missing.
  • xibo_woocommerce_cms_existing_instance_title: Select list dropdown for existing CMS instances
  • xibo_woocommerce_cms_instance_message: Form field message for entering a new CMS instance name
  • xibo_woocommerce_cms_instance_error: Validation message when a CMS instance name or CMS instance select list item is missing.
  • xibo_woocommerce_android_no_licences_to_upgrade: The customer has added an android upgrade product to the cart, but doesn’t have any licence pools to upgrade.
  • xibo_woocommerce_xfa_version_upgrade_error: The customer hasn’t selected a licence pool to add upgrade licences to.

It is possible to output some HTML immediately after the heading for “additional information” by implementing a filter for xibo_woocommerce_order_notes_header.

It is also possible to capture generate API messages when submitting a cart for validation or checkout by implementing a filter for xibo_woocommerce_api_exception.

An example of filtering one of these messages would be:

add_filter('xibo_woocommerce_xfa_licence_email_message', function ($message) { 
    return 'Custom message about adding licence email addresses'; 
});

Implementation Notes

The plugin makes use of the following 3 hooks to add and capture information during the checkout process:

  1. woocommerce_after_order_notes
  2. woocommerce_checkout_process
  3. woocommerce_checkout_update_order_meta

Step 1 checks the active cart for products containing an API code and creates form fields on the checkout page, step 2 validates the form fields created in step 1 and step 3 captures and stores the data entered/validated in steps 1 and 3. During step 1, the fields are created inside a <div> per product, with a <h3> heading and then the field.

<div>'s are created with the class product_checkout_field and class xfa_product_checkout_field for android / cms_product_checkout_field for CMS. These can be styled using the active theme’s style sheet.

This happens for all products which have had their Xibo Platform product selected when configuring them.

Provisioning

The plugin will listen for orders transitioning into the Processing or Complete states. At this point the order details are sent to the Xibo Platform for provisioning. If the order is for a logged in user, this users ID will also be sent at this point. The user Id will be matched in XP for a sub-company owned by the reseller company, if one does not exist it will be created. The order line items will be provisioned for the sub-company - billing will be for the reseller company (the company credentials accessing the API). If no user ID is present (guest checkout), the order line items will be assigned to the reseller company directly.

Depending on the products selected provisioning my be immediate or take up to 30 minutes. When complete the Xibo Platform calls WC with the order details and the these will be back-filled as custom attributes on the order. An email is also sent to the reseller account billing email address.

Email Notifications

It is likely that the standard email notifications generated by WC should be enhanced with information provided by the XP. This is particularly true for CMS instances where the customer will need their address, key and secret.

During provisioning the XP will use a web hook to update the order status and other order attributes once the order has been provisioned fully.

The email notification can then be overridden to test for these fields:

  • xibo_cloud_url
  • xibo_cloud_server_key
  • xibo_cloud_user
  • xibo_cloud_password

Flow overview

The complete flow is shown below:


Xibo Platform API