Javascript setup
This guide will help you setup the SeatCurve javascript application ready for use on your website, this guide assumes you have completed the Server Setup guide and have a working middleware application ready for use.
Javascript Installation
SeatCurve Javascript Library
SeatCurve is a Javascript application, in order to use SeatCurve on a web page you must first load the SeatCurve Javascript library, to do so add the following code to your webpage:
<script src="/syos-bundle.js"></script>
SeatCurve Root element
Next you will need to define where to load SeatCurve, to do this you will need to create a HTML element with a unique id that will act as the SeatCurve root element, for this example we will use the id syos-root
add the following code to your webpage:
<div id="syos-root"></div>
Initialization
SeatCurve needs to be initialized before it can be used, as a minimum SeatCurve needs the following information:
- Current performance number
- Current facility number
- URL to the SeatCurve backend API (See Server Setup)
- Where to redirect to once tickets have been added to the cart
The SeatCurve Javascript library we loaded earlier gives us access To a new SYOS class, To initialize SeatCurve with the above information we create a new instance of this SYOS class passing in a configuration object with the above information. See below for an example:
<script>
var syosApp = new SYOS({
initialPerfNo: 1620,
initialFacilityNo: 12,
endpoint: 'https://example.seatcurve.api/rest-proxy',
onComplete: function() {
window.location.href = '/booking/basket';
}
});
</script>
Lets run through each line to explain what is happening:
var syosApp = new SYOS({
Creates a new variable syosApp
and passes in a new instance of the SeatCurve SYOS object
initialPerfNo: 1620,
Tells SeatCurve what performance ID to load.
initialFacilityNo: 12,
Tells SeatCurve what Facility/Venue ID to load.
endpoint: 'https://example.seatcurve.api/rest-proxy',
Tells SeatCurve the URL of the SeatCurve API.
onComplete: function() {
window.location.href = '/booking/basket';
}
onComplete is a function that runs once SeatCurve has finished adding tickets to the basket, in this example we are redirecting the user to a '/booking/basket' page once the tickets are added to the basket.
Running SeatCurve
Now that we have the SeatCurve Javascript library loaded, A element with a unique ID for SeatCurve and SeatCurve initialized all we need to do now is tell SeatCurve to run:
var rootEl = document.getElementById('syos-root');
syosApp.run(rootEl);
Notice that we used the syos-root
ID above, this is the ID of the element we created earlier and is how SeatCurve knows where on the page to render.
Putting it all together
Putting the above steps together the HTML needed to run SeatCurve should now look like this:
<script src="/syos-bundle.js"></script>
<div id="syos-root"></div>
<script id="script-syos-run">
var syosApp = new SYOS({
initialPerfNo: 1620,
initialFacilityNo: 12,
endpoint: 'https://example.seatcurve.api/rest-proxy',
onComplete: function() {
window.location.href = '/booking/basket';
}
});
var rootEl = document.getElementById('syos-root');
syosApp.run(rootEl);
</script>
SeatCurve Configuration
There are two main points of configuration. Essential configuration is passed into the SYOS constructor when initialising the app. All other config is defined via a global SYOSConfig object.
Essential Configuration Options
Name | Description | Required? |
---|---|---|
endpoint | URL to proxy endpoint. | (required) |
onComplete | On-complete callback. Called after successfully adding or updating seats. Use this to redirect on to your cart page. | (required) |
initialSessionKey | Customer Session key to use | (optional) |
initialPerfNo | Performance number to use | (required if loading a performance) |
initialPkgNo | Package number to use | (required if loading a package) |
initialFacilityNo | Facility number for the performance or package. Used to determine which seat-map graphic to use. | (required if using a custom seat-map graphic) |
initialMos | Current mode-of-sale. If provided alongside the initialPromoCode option we can avoid making a call to loginInfo. If omitted we’ll explicitly call loginInfo | (optional) |
initialPromoCode | Current promo source-code. If provided alongside the initialMos option we can avoid making a call to loginInfo. Of omitted we’ll explicitly call loginInfo | (optional) |
Global Configuration Options
The following documents the available configuration options that can be configured through the global SYOSConfig object.
Name | Description | Required? |
---|---|---|
currencyCode | Currency for display. Supports GBP or USD. | (optional, defaults to USD) |
dateTimeFormat | Date format used for performance dates. Uses date-fns/format | (optional, defaults to MMMM D, YYYY [at] h:mma) |
returnUrl | If defined a UI back button will be displayed and this URL will be used as a return location | (optional) |
maxTicketsMessage | Message to be displayed when hitting the max-tickets limit | (optional, defaults to “You cannot select any more seats.”) |
customMaxTicketsLimit | Provide a custom max-tickets limit. Will use the value from GetMaxTicketAmount if not set | (optional) |
facilityMapping | Configures seat-map and level-selector graphics for individual facilities | (optional, but required if using a custom seat-map graphic) |
basket | Provides the following options for configuring messaging for the mini-basket: totalLabel, submitLabel, successLabel, updateLabel, processingLabel, extraMessages[] | (optional, defaults to US-centric wording) |
seatTypes | Configure seat types. Mostly used to configure custom seat icons like ADA seating or restricted view. Custom seat icons can be associated with either hold-codes or seat-type IDs. | (optional) |
seatMessages | Custom seat messages. An Array of possible messages to show for a seat, messages can be associated with one or more seat type or hold codes. | (optional) |
Feature Flags
As part of the global SYOSConfig object, there is a subobject of this global config used for feature flags. Feature flags are used to configure optional functionality. They allow us to keep the core functionality lean yet provide configurable additional functionality, The basic format looks something like this:
window.SYOSConfig = {
features: {
promoCode: {
// Boolean flag to enable/disable feature
enabled: true,
// Additional custom properties to configure the feature
myCustomOption: null
}
},
// top-level config here
};
Available feature flags are as follows:
Name | Description |
---|---|
metrics | Log usage metrics to Google Analytics. Enabled by default. |
bestAvailableLink | If enabled a choose best available button will be shown on both the level-selector screen (if enabled) and in the seat-map controls. |
promoCode | Display a promo-code form on the level-selector and seat-map |
levelSelector | If enabled renders an additional level-selector screen before the main seat-map. Useful for quick navigation in large venues and to introduce the venue using imagery. |
panZoom | Pan zoom behaviour. It would be weird to disable this one but the options provided allow you to adjust min/max zoom threshold and zoom sensitivity. Enabled by default. |
customSeatDescription | If enabled allows you to customise the format used for seat descriptions. Accepts a customiser function which passes through the full seat data object for you to use to determine to construct your own set description. |
details | Performance details. Allows a web content field ID to be provided to override the standard title returned by GetPerformanceDetailWithDiscountingEx |
performanceSelector | If enabled displays a performance switcher in the seat-map controls allowing you to switch between performances within the app. |
cacheableGetSeats | Enables a calls to the custom GetSeatsBriefWithMOS method described in the API intergration section. Enabled by default. |
preferredPriceType | If enabled then the application will select the same price type for subsequent seats as long as it has the same hold code, zone, and seat type. Enabled by default. |
priceFilters | If enabled displays a price key allowing people to filter seats on the seat-map by price. Enabled by default. |
seatKey | If enabled displays a seat key showing icons for each of the available types of seat. Enabled by default. |
viewFromSeat | If enabled displays inline view from seat imagery. Full implementation details are described later in the document. |
Note: imageBackground, imageForeground, and imageMask are all paths to the location of each graphic. zoomLevel determines how far to zoom in when selecting a hit-area. hitAreaLabels let’s you provide a mapping between the hit-area layer names and a meaningful label.
View From Seat Imagery
SeatCurve has a feature which allows you to provide a mapping of seat images for a facility, the application will use a nearest neighbor algorithm to determine the best seat to show.
This allows you to supply a relatively small number of images and still fill the venue. Whilst we encourage you to provide as many high-quality seat images as you can, you do not need to provide an image for every single seat.
JSON Feed Specification
In order to show view from seat images you must generate a JSON feed in the following format. How this feed is implemented is up to you but it is typically a static JSON file hosted on your website.
{
"facilities": [{
"facility_no": "10",
"seat_images": [
"https://static.example.com/path/to/images/seat-1-A-2.png",
"https://static.example.com/path/to/images/seat-2-A-2.png",
"https://static.example.com/path/to/images/seat-3-A-2.png"
]
}]
}
The image file-name needs to be in the format seat-{number}-{row}-{screen}, e.g. seat-42-A-2. This is the same format as the seat id's used in the seatmap graphic.
To tell the application to use this feed you need to configure the viewFromSeat feature flag as follows:
window.SYOSConfig = {
features: {
viewFromSeat: {
enabled: false,
endpoint: 'https://static.example.com/path/to/images/seat-images.json',
// If enabled shows a caption describing the real location of the seat image.
showCaption: true
}
…
}
}
Analytics Data
SeatCurve has built-in support for Google Analytics Custom Events and tracks a number of metrics out of the box. The full list of metrics are as follows:
Name | Description |
---|---|
Seat Selected | Tracked when adding a seat to the mini-cart, includes a description of the seat that was selected. |
Seat Removed | Tracked when removing a seat from the mini-cart, includes a description of the seat that was removed. |
Refresh Seat Availability | Tracked when a seat-collision occurs and users are prompted to refresh the seat availability. |
Filter Prices | Tracked when using the price filters, includes which price was selected. |
Selected Level | Tracked when switching between levels using the control-panel for multi-level venues. Includes which level was selected. |
Toggle Cart | Tracked when toggling the cart open or closed |
Toggle Control-Panel | Tracked when toggling the controls open or closed |
This data has been very useful and helped inform future development and guide technical decisions on support tickets. The more we can track the better.