The compiled library is hosted on Github. Cloudflare is used to serve the files to the front end.
Deploying is scripted via NPM. (clear-cache.sh and deploy.sh will need executable permissions before running).
$ npm run deploy
A bundled and minified version of Bridge must be imported into each page of an eCommerce site, not including terms, privacy, contact pages. Bridge is also dependant on jQuery, therefore jQuery must be imported above Bridge in every offerpage.
<script id='bridge-controller' src='https://bridge-middletier.xyz/dist/v1/bridge.min.js' data-url='<URL of a Maestro Instance>'></script>
<link rel='stylesheet' href='https://bridge-middletier.xyz/dist/v1/bridge.min.css'>
The imports for Bridge must be in this format. The script import uses id='bridge-controller'
to identify the controller, and the data-url
attribute will represent the desired instance of Maestro’s transaction server URL (in the format of: somedomain.com). This will be passed to Transaction.js and used to make calls to Maestro’s API.
Transaction.js is the bridge between eCommerce pages and Maestro. It provides three forms preconfigured to properly connect with Maestro’s transaction server. Using these forms, an eCommerce page can, create prospects, create initial orders and create additional orders. It will also automatically package additional information required to place orders, such as site id, IP address etc.
All forms emit a spinner-on
event on submission and a spinner-off
event if error after submission. These events are used to control the visibility of the Spinner.js processing spinner.
Transaction.js and Maestro use a JSON Web Token to pass information between the eCommerce page and the browser. Interaction with the token is usually not necessary as all interaction is handled automatically in Bridge, however this token may be read to retieve user information, such as name and address. See the Utilities GetUserInfo section for details on reading the token.
Below are details on integrating an eCommerce page.
Maestro requires a site id to be present for every call to its API. This site id must be present in the url as a parameter ?id=xxxx
and must only be present in the url on the first page load. This site id will be immediately retrieved and stored in the browser’s sessionStorage for later use by Bridge. If no site id is present, Maestro will respond with an error message.
Integrating with the three forms requires several steps.
Identify the form with the appropriate id.
Provide an input for each required field.
Insure the inputs have the required
attribute (if appropriate).
Insure the form does not have the no validate
attribute.
To identify a form, provide one of the options as the form’s id
attribute. There are three options of form to choose from.
The use of forms must follow the flow of ProspectForm
-> PaymentForm
-> UpsellForm
. More than one UpsellForm
can be used if needed however a PaymentForm
must always be used before any UpsellForms
can be used.
Each form has its own required inputs. Forms also have an optional hidden input named nextPage
that can control the next page to go to after this form is submitted. If nextPage
is not provided, Bridge will follow the default page flow of: index.html
-> payment.html
-> promo.html
-> ../receipt.html
. In most situations, nextPage
does not need to be used.
ProspectForm
<form id='ProspectForm'>
<!-- OPTIONAL -->
<input type='hidden' name='nextPage' value='some-page.html'>
<!-- REQUIRED -->
<input name='firstName' required>
<input name='lastName' required>
<input name='address1' required>
<input name='city' required>
<select name='state' required></select>
<input name='zip' required>
<input name='phone' required>
<input name='email' required>
</form>
PaymentForm - *Important. Each eCommerce page must provide its own logic for making the billing address fields required based on the value of billingSameAsShipping
.
<form id='PaymentForm'>
<!-- OPTIONAL -->
<input type='hidden' name='nextPage' value='some-page.html'>
<!-- REQUIRED -->
<input type='hidden' name='productCode' value='some-product-code'>
<input type='radio' name='billingSameAsShipping' value='yes' checked>
<input type='radio' name='billingSameAsShipping' value='no'>
<input name='creditCardNumber' required>
<select name='creditCardType' required></select>
<select name='expiryMonth' required></select>
<select name='expiryYear' required></select>
<input name='CVV' required>
<!-- REQUIRED IF (billingSameAsShipping === 'no') -->
<input name='billingFirstName'>
<input name='billingLastName'>
<input name='billingAddress1'>
<input name='billingCity'>
<select name='billingState'></select>
<input name='billingZip'>
</form>
UpsellForm
<form id='UpsellForm'>
<!-- OPTIONAL -->
<input type='hidden' name='nextPage' value='some-page.html'>
<!-- REQUIRED -->
<input type='hidden' name='productCode' value='some-other-product-code'>
</form>
A preconfigured validation library. Give your form inputs the required names and Validation.js will do the rest.
Validation.js will apply a or
image on all
Input
or Select
elements after a user has changed the elements value, indicating a valid or invalid value.
It will also apply number only
and min/max length
rules for elements 'zip'
, 'phone'
, 'creditCardNumber'
and 'CVV'
, automatically setting their type to tel
.
Maestro requires most form inputs to be required
. Each eCommerce page will be responsible for setting the appropriate inputs as required and must insure that no validate
IS NOT set on the form.
Please see Transaction.js for full information on proper form integration.
Modal.js is a simplifed popup window framework used for displaying Terms & Conditions, Contact, Privacy Policy etc in a closable popup modal, without leaving the current page, lowering user bounce rates.
To use a modal, create an anchor tag with the class 'bridge-modal'
and the path to the desired page as the href
. Bridge will open this link in a popup modal. Use this for all footer links, or links to any terms, privacy pages.
<a href='path-to-file.html' class='bridge-modal'>Click Here</a>
Mobile-Redirect.js will redirect a user to/from the desktop/mobile versions of an eCommerce page, based on the screen size of their device.
function redirectIfMobile(path?: string);
function redirectIfDesktop(path?: string);
From a desktop page:
<!--redirects the user to the mobile version if they are on mobile-->
<script>redirectIfMobile()</script>
From a mobile page:
<!--redirects the user to the desktop version if they are on desktop-->
<script>redirectIfDesktop()</script>
Only make these function calls from the index page of each version (desktop or mobile). It will redirect using the default folder structure (/desktop/mobile). If a different redirect path is needed, each function will accept a new path as an argument. In most situations, the default path will work. This function call must be placed below the import for Bridge.js.
Spinner.js is a processing spinner triggered by spinner-on
/spinner-off
events emitted by Transaction.js. It will automatically appear after submitting any of the three forms provided by Transaction.js. No setup is required
The processing spinner contains a default message, however this can be overridden with a custom message by calling the spinnerText({})
function and providing header
, body
or footer
values. To override the default message, this function call will need to be on every page where the processing spinner pop up will be present.
function spinnerText(message: { header?: string, body?: string, footer?: string });
Example:
<script>
spinnerText({
header: 'Header text',
body: 'Body text',
footer: 'Footer text'
})
</script>
Bridge contains several utilities in Javascript and CSS
The following are general utility functions provided by Bridge.
This function returns the decoded contents of the Transaction.js JSON Web Token as an object. It accepts an optional parameter JSON web token string for development purposes. In production, no parameter is required.
function GetUserInfo(token?: string);
Example:
const user = GetUserInfo()
console.log(user.firstName)
console.log(user.lastName)
console.log(user.email)
The following are general utility css classes provided by Bridge.
Give an element a pulsing appearance. Useful for buttons.